@decocms/blocks 7.1.1 → 7.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks",
-  "version": "7.1.1",
+  "version": "7.2.0",
   "type": "module",
   "description": "Deco framework-agnostic core: CMS block resolution, section registry, matchers, portable SDK utilities",
   "repository": {
@@ -21,6 +21,15 @@
     "./matchers/builtins": "./src/matchers/builtins.ts",
     "./matchers/posthog": "./src/matchers/posthog.ts",
     "./matchers/override": "./src/matchers/override.ts",
+    "./flags/audience": "./src/flags/audience.ts",
+    "./flags/everyone": "./src/flags/everyone.ts",
+    "./flags/flag": "./src/flags/flag.ts",
+    "./flags/types": "./src/flags/types.ts",
+    "./flags/multivariate": "./src/flags/multivariate.ts",
+    "./flags/multivariate/image": "./src/flags/multivariate/image.ts",
+    "./flags/multivariate/message": "./src/flags/multivariate/message.ts",
+    "./flags/multivariate/page": "./src/flags/multivariate/page.ts",
+    "./flags/multivariate/section": "./src/flags/multivariate/section.ts",
     "./middleware": "./src/middleware/index.ts",
     "./middleware/healthMetrics": "./src/middleware/healthMetrics.ts",
     "./middleware/hydrationContext": "./src/middleware/hydrationContext.ts",

package/src/flags/audience.ts

@@ -0,0 +1,56 @@
+import type { FlagObj, Matcher } from "./types";
+import Flag from "./flag";
+
+/**
+ * @title Site Route
+ * @titleBy pathTemplate
+ */
+export interface Route {
+  pathTemplate: string;
+  /**
+   * @description if true so the path will be checked against the coming from request instead of using urlpattern.
+   */
+  isHref?: boolean;
+  handler: {
+    value: unknown;
+  };
+  /**
+   * @title Priority
+   * @description higher priority means that this route will be used in favor of other routes with less or none priority
+   */
+  highPriority?: boolean;
+}
+
+/**
+ * @title Routes
+ * @description Used to configure your site routes
+ */
+export type Routes = Route[];
+
+/**
+ * @titleBy name
+ */
+export interface Audience {
+  matcher: Matcher;
+  /**
+   * @title The audience name (will be used on cookies).
+   * @description Add a meaningful short word for the audience name.
+   * @minLength 3
+   * @pattern ^[A-Za-z0-9_-]+$
+   */
+  name: string;
+  routes?: Routes;
+}
+
+/**
+ * @title Audience
+ * @description Select routes based on the matched audience.
+ */
+export default function Audience({ matcher, routes, name }: Audience): FlagObj<Route[]> {
+  return Flag<Route[]>({
+    matcher,
+    true: routes ?? [],
+    false: [],
+    name,
+  });
+}

package/src/flags/everyone.ts

@@ -0,0 +1,29 @@
+import type { FlagObj, Matcher } from "./types";
+import Audience, { type Route, type Routes } from "./audience";
+
+/**
+ * Ported from apps-start's `website/matchers/always.ts`. That file existed
+ * as its own block file only because deco-cx's old manifest system
+ * discovered matchers by scanning files; this codebase's matcher/flag
+ * mechanisms aren't file-scanned, so it's inlined here as its sole
+ * consumer. (Its `cacheable = true` export was manifest-generation
+ * metadata for that old system with no runtime consumer — dropped, same
+ * as the rest of the `date`/matcher ports in `../matchers/builtins.ts`.)
+ */
+const MatchAlways: Matcher = () => true;
+
+export interface EveryoneConfig {
+  routes?: Routes;
+}
+
+/**
+ * @title Audience Everyone
+ * @description Always match regardless of the current user
+ */
+export default function Everyone({ routes }: EveryoneConfig): FlagObj<Route[]> {
+  return Audience({
+    matcher: MatchAlways,
+    routes: routes ?? [],
+    name: "Everyone",
+  });
+}

package/src/flags/flag.ts

@@ -0,0 +1,15 @@
+import type { FlagObj } from "./types";
+
+export type Props<T> = FlagObj<T>;
+
+/**
+ * @title Flag
+ */
+export default function Flag<T>({ matcher, name, true: T, false: F }: Props<T>): FlagObj<T> {
+  return {
+    matcher,
+    true: T,
+    false: F,
+    name,
+  };
+}

package/src/flags/flags.test.ts

@@ -0,0 +1,148 @@
+import { describe, expect, it } from "vitest";
+import Audience from "./audience";
+import Everyone from "./everyone";
+import Flag from "./flag";
+import type { Matcher } from "./types";
+import multivariate from "./utils/multivariate";
+import ImageVariants from "./multivariate/image";
+import MessageVariants from "./multivariate/message";
+import PageVariants from "./multivariate/page";
+import SectionVariants from "./multivariate/section";
+
+// ---------------------------------------------------------------------------
+// flag.ts
+// ---------------------------------------------------------------------------
+
+describe("Flag", () => {
+  it("returns a FlagObj with the same values", () => {
+    const matcher: Matcher = () => true;
+    const result = Flag({
+      matcher,
+      true: "variant-a",
+      false: "variant-b",
+      name: "test-flag",
+    });
+
+    expect(result.matcher).toBe(matcher);
+    expect(result.true).toBe("variant-a");
+    expect(result.false).toBe("variant-b");
+    expect(result.name).toBe("test-flag");
+  });
+
+  it("preserves complex true/false values", () => {
+    const routes = [{ pathTemplate: "/*", handler: { value: {} } }];
+    const result = Flag<typeof routes>({
+      matcher: () => false,
+      true: routes,
+      false: [],
+      name: "routes-flag",
+    });
+
+    expect(result.true).toBe(routes);
+    expect(result.false).toEqual([]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// audience.ts
+// ---------------------------------------------------------------------------
+
+describe("Audience", () => {
+  it("returns FlagObj with routes as true branch and empty as false", () => {
+    const matcher: Matcher = () => true;
+    const routes = [{ pathTemplate: "/products/*", handler: { value: {} } }];
+
+    const result = Audience({ matcher, name: "vip-users", routes });
+
+    expect(result.name).toBe("vip-users");
+    expect(result.true).toEqual(routes);
+    expect(result.false).toEqual([]);
+  });
+
+  it("defaults routes to empty array when not provided", () => {
+    const result = Audience({ matcher: () => false, name: "empty" });
+
+    expect(result.true).toEqual([]);
+    expect(result.false).toEqual([]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// everyone.ts
+// ---------------------------------------------------------------------------
+
+describe("Everyone", () => {
+  it("creates a flag named Everyone that always matches", () => {
+    const routes = [{ pathTemplate: "/*", handler: { value: {} } }];
+    const result = Everyone({ routes });
+
+    expect(result.name).toBe("Everyone");
+    expect(result.true).toEqual(routes);
+    expect(result.false).toEqual([]);
+    // The matcher should be MatchAlways which returns true
+    expect(result.matcher({} as any)).toBe(true);
+  });
+
+  it("works with no routes", () => {
+    const result = Everyone({});
+
+    expect(result.name).toBe("Everyone");
+    expect(result.true).toEqual([]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// multivariate
+// ---------------------------------------------------------------------------
+
+describe("multivariate", () => {
+  it("returns the variants as-is", () => {
+    const variants = [
+      { value: "A", weight: 0.5 },
+      { value: "B", weight: 0.5 },
+    ];
+
+    const result = multivariate({ variants });
+
+    expect(result.variants).toBe(variants);
+    expect(result.variants).toHaveLength(2);
+  });
+
+  it("supports variants with matchers", () => {
+    const matcher: Matcher = () => true;
+    const variants = [{ value: "control", matcher }, { value: "default" }];
+
+    const result = multivariate({ variants });
+
+    expect(result.variants[0].matcher).toBe(matcher);
+    expect(result.variants[1].matcher).toBeUndefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// multivariate/* (Image/Message/Page/Section variants) + the multivariate.ts
+// re-export (`./multivariate.ts` re-exports `./multivariate/page.ts`'s
+// default, so `PageVariants` doubles as the coverage for that re-export).
+// ---------------------------------------------------------------------------
+
+describe("multivariate/*", () => {
+  it("Image delegates to multivariate", () => {
+    const variants = [{ value: "a.png" }, { value: "b.png" }];
+    expect(ImageVariants({ variants })).toEqual({ variants });
+  });
+
+  it("Message delegates to multivariate", () => {
+    const variants = [{ value: "hello" }, { value: "world" }];
+    expect(MessageVariants({ variants })).toEqual({ variants });
+  });
+
+  it("Page delegates to multivariate", () => {
+    const variants = [{ value: [] }, { value: [] }];
+    expect(PageVariants({ variants })).toEqual({ variants });
+  });
+
+  it("Section delegates to multivariate", () => {
+    const variants = [{ value: {} }, { value: {} }];
+    expect(SectionVariants({ variants })).toEqual({ variants });
+  });
+});

package/src/flags/multivariate/image.ts

@@ -0,0 +1,11 @@
+import type { ImageWidget, MultivariateFlag } from "../types";
+import multivariate, { type MultivariateProps } from "../utils/multivariate";
+
+/**
+ * @title Image Variants
+ */
+export default function Image(
+  props: MultivariateProps<ImageWidget>,
+): MultivariateFlag<ImageWidget> {
+  return multivariate(props);
+}

package/src/flags/multivariate/message.ts

@@ -0,0 +1,11 @@
+import type { MultivariateFlag } from "../types";
+import multivariate, { type MultivariateProps } from "../utils/multivariate";
+
+export type Message = string;
+
+/**
+ * @title Message Variants
+ */
+export default function Message(props: MultivariateProps<Message>): MultivariateFlag<Message> {
+  return multivariate(props);
+}

package/src/flags/multivariate/page.ts

@@ -0,0 +1,16 @@
+import type { MultivariateFlag } from "../types";
+import multivariate, { type MultivariateProps } from "../utils/multivariate";
+
+/**
+ * Section type placeholder — the actual Section type is defined by the framework.
+ */
+type Section = unknown;
+
+/**
+ * @title Page Variants
+ */
+export default function PageVariants(
+  props: MultivariateProps<Section[]>,
+): MultivariateFlag<Section[]> {
+  return multivariate(props);
+}

package/src/flags/multivariate/section.ts

@@ -0,0 +1,16 @@
+import type { MultivariateFlag } from "../types";
+import multivariate, { type MultivariateProps } from "../utils/multivariate";
+
+/**
+ * Section type placeholder — the actual Section type is defined by the framework.
+ */
+type Section = unknown;
+
+/**
+ * @title Section Variants
+ */
+export default function SectionVariants(
+  props: MultivariateProps<Section>,
+): MultivariateFlag<Section> {
+  return multivariate(props);
+}

package/src/flags/multivariate.ts

@@ -0,0 +1 @@
+export { default } from "./multivariate/page";

package/src/flags/types.ts

@@ -0,0 +1,59 @@
+/**
+ * Types for the feature-flag primitives in this subpath.
+ *
+ * Ported from apps-start's `website/types.ts` (the flag/matcher slice only).
+ * These are intentionally self-contained: `Matcher`/`MatchContext` here are
+ * a *function-composition* matcher — a plain `(ctx) => boolean` imported and
+ * invoked directly by TS code — which is a different mechanism from
+ * `@decocms/blocks/matchers`'s CMS rule engine (`registerMatcher`/
+ * `evaluateMatcher` dispatch by name over a `Record<string, unknown>` rule
+ * against `MatcherContext` from `cms/resolve.ts`). The two don't share a
+ * context shape (this `MatchContext` has `device`/`siteId`; the CMS one
+ * doesn't), so they are not merged.
+ */
+import type { ImageWidget } from "../types/widgets";
+
+export type { ImageWidget };
+
+/**
+ * Context passed to matchers at request time.
+ * The framework populates this from the incoming request.
+ */
+export interface MatchContext {
+  request: Request;
+  device: "mobile" | "tablet" | "desktop";
+  siteId: number;
+}
+
+/**
+ * A matcher is a function that evaluates request context and returns a boolean.
+ */
+export type Matcher = (ctx: MatchContext) => boolean;
+
+/**
+ * A feature flag with a matcher and two branches.
+ * The framework evaluates the matcher at request time and selects the
+ * appropriate branch value.
+ */
+export interface FlagObj<T> {
+  matcher: Matcher;
+  true: T;
+  false: T;
+  name: string;
+}
+
+/**
+ * A single variant in a multivariate flag.
+ */
+export interface Variant<T> {
+  matcher?: Matcher;
+  value: T;
+  weight?: number;
+}
+
+/**
+ * A multivariate flag with multiple variants, each with its own matcher.
+ */
+export interface MultivariateFlag<T> {
+  variants: Variant<T>[];
+}

package/src/flags/utils/multivariate.ts

@@ -0,0 +1,20 @@
+import type { MultivariateFlag, Variant } from "../types";
+
+/**
+ * @title Multivariate
+ */
+export interface MultivariateProps<T> {
+  /**
+   * @minItems 1
+   * @addBehavior 1
+   */
+  variants: Variant<T>[];
+}
+
+/**
+ * @title Variant
+ * @label hidden
+ */
+export default function multivariate<T>(props: MultivariateProps<T>): MultivariateFlag<T> {
+  return props;
+}

package/src/hooks/Image.test.ts

@@ -0,0 +1,100 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { getOptimizedMediaUrl, getSrcSet } from "./Image";
+
+describe("getOptimizedMediaUrl", () => {
+	let warnSpy: ReturnType<typeof vi.spyOn>;
+	let prevNodeEnv: string | undefined;
+
+	beforeEach(() => {
+		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("returns empty string and warns when src is undefined", () => {
+		const result = getOptimizedMediaUrl({
+			originalSrc: undefined as unknown as string,
+			width: 100,
+			fit: "cover",
+		});
+		expect(result).toBe("");
+		expect(warnSpy).toHaveBeenCalledTimes(1);
+		expect(warnSpy.mock.calls[0][0]).toMatch(/empty\/undefined src/);
+	});
+
+	it("returns empty string when src is empty", () => {
+		const result = getOptimizedMediaUrl({
+			originalSrc: "",
+			width: 100,
+			fit: "cover",
+		});
+		expect(result).toBe("");
+	});
+
+	it("returns empty string when src is null", () => {
+		const result = getOptimizedMediaUrl({
+			originalSrc: null as unknown as string,
+			width: 100,
+			fit: "cover",
+		});
+		expect(result).toBe("");
+	});
+
+	it("does NOT warn in production for missing src", () => {
+		process.env.NODE_ENV = "production";
+		const result = getOptimizedMediaUrl({
+			originalSrc: undefined as unknown as string,
+			width: 100,
+			fit: "cover",
+		});
+		expect(result).toBe("");
+		expect(warnSpy).not.toHaveBeenCalled();
+	});
+
+	it("returns data URI as-is", () => {
+		const dataUri = "data:image/png;base64,iVBORw0KGgo=";
+		expect(
+			getOptimizedMediaUrl({
+				originalSrc: dataUri,
+				width: 100,
+				fit: "cover",
+			}),
+		).toBe(dataUri);
+	});
+
+	it("routes through Deco image CDN for arbitrary src", () => {
+		const result = getOptimizedMediaUrl({
+			originalSrc: "https://cdn.example.com/foo.jpg",
+			width: 200,
+			fit: "cover",
+		});
+		expect(result).toContain("/image?");
+		expect(result).toContain("width=200");
+		expect(result).toContain("fit=cover");
+		expect(result).toContain("src=https://cdn.example.com/foo.jpg");
+	});
+});
+
+describe("getSrcSet", () => {
+	it("returns undefined when src is undefined", () => {
+		expect(getSrcSet(undefined as unknown as string, 100)).toBeUndefined();
+	});
+
+	it("returns undefined when src is empty", () => {
+		expect(getSrcSet("", 100)).toBeUndefined();
+	});
+
+	it("produces a srcset string for valid src", () => {
+		const result = getSrcSet("https://cdn.example.com/foo.jpg", 100);
+		expect(result).toBeDefined();
+		// Each factor entry is "<url> <width>w".
+		expect(result).toMatch(/\d+w/);
+		expect(result).toContain("foo.jpg");
+	});
+});