@decocms/apps 1.1.2 → 1.3.0

package/website/matchers/location.ts

@@ -0,0 +1,113 @@
+import type { MatchContext } from "../types";
+import { haversine } from "../utils/location";
+
+export interface Coordinate {
+	latitude: number;
+	longitude: number;
+	radius?: number;
+}
+
+export interface Map {
+	/**
+	 * @title Area selection
+	 * @example -7.27820,-35.97630,2000
+	 */
+	coordinates?: string;
+}
+
+export interface Location {
+	/**
+	 * @title City
+	 * @example São Paulo
+	 */
+	city?: string;
+	/**
+	 * @title Region Code
+	 * @example SP
+	 */
+	regionCode?: string;
+	/**
+	 * @title Country
+	 * @example BR
+	 */
+	country?: string;
+}
+
+export interface Props {
+	/** @title Include Locations */
+	includeLocations?: (Location | Map)[];
+	/** @title Exclude Locations */
+	excludeLocations?: (Location | Map)[];
+}
+
+export interface MapLocation {
+	city?: string;
+	regionCode?: string;
+	country?: string;
+	coordinates?: string;
+}
+
+const matchLocation =
+	(defaultNotMatched = true, source: MapLocation) =>
+	(target: MapLocation) => {
+		if (!target.regionCode && !target.city && !target.country && !target.coordinates) {
+			return defaultNotMatched;
+		}
+		let result = !target.regionCode || target.regionCode === source.regionCode;
+		result &&=
+			!source.coordinates ||
+			!target.coordinates ||
+			haversine(source.coordinates, target.coordinates) <= Number(target.coordinates.split(",")[2]);
+		result &&= !target.city || target.city === source.city;
+		result &&= !target.country || target.country === source.country;
+		return result;
+	};
+
+function fixEncoding(input: string): string {
+	try {
+		const utf8bytes = [...input].map((char) => char.charCodeAt(0));
+		return new TextDecoder("utf-8").decode(Uint8Array.from(utf8bytes));
+	} catch {
+		return input;
+	}
+}
+
+const escaped = ({ city, country, regionCode, coordinates }: MapLocation): MapLocation => {
+	return {
+		coordinates,
+		regionCode,
+		city: city ? fixEncoding(city) : city,
+		country: country ? fixEncoding(country) : country,
+	};
+};
+
+/**
+ * @title Location
+ * @description Target users based on their geographical location, such as country, city, or region
+ * @icon map-2
+ */
+export default function MatchLocation(
+	{ includeLocations, excludeLocations }: Props,
+	{ request }: MatchContext,
+) {
+	const city = request.headers.get("cf-ipcity") ?? undefined;
+	const country = request.headers.get("cf-ipcountry") ?? undefined;
+	const regionCode = request.headers.get("cf-region-code") ?? undefined;
+	const latitude = request.headers.get("cf-iplatitude") ?? undefined;
+	const longitude = request.headers.get("cf-iplongitude") ?? undefined;
+	const coordinates = latitude ? `${latitude},${longitude}` : undefined;
+
+	const userLocation = { city, country, regionCode, coordinates };
+	const isLocationExcluded =
+		excludeLocations?.some(matchLocation(false, escaped(userLocation))) ?? false;
+
+	if (isLocationExcluded) {
+		return false;
+	}
+
+	if (includeLocations?.length === 0) {
+		return true;
+	}
+
+	return includeLocations?.some(matchLocation(true, escaped(userLocation))) ?? true;
+}

package/website/matchers/multi.ts

@@ -0,0 +1,24 @@
+import type { MatchContext, Matcher } from "../types";
+
+/**
+ * @title Combined options with {{{op}}}
+ */
+export interface Props {
+	op: "or" | "and";
+	matchers: Matcher[];
+}
+
+/**
+ * @title Multi
+ * @description Create more complex conditions by combining multiple matchers
+ * @icon plus
+ */
+const MatchMulti =
+	({ op, matchers }: Props) =>
+	(ctx: MatchContext) => {
+		return op === "or"
+			? matchers.some((matcher) => matcher(ctx))
+			: matchers.every((matcher) => matcher(ctx));
+	};
+
+export default MatchMulti;

package/website/matchers/negate.ts

@@ -0,0 +1,21 @@
+import type { MatchContext, Matcher } from "../types";
+
+export interface Props {
+	/**
+	 * @description Matcher to be negated.
+	 */
+	matcher: Matcher;
+}
+
+/**
+ * @title Negates
+ * @description Create conditions that target users who do not meet certain criteria
+ * @icon minus
+ */
+const NegateMatcher =
+	({ matcher }: Props) =>
+	(ctx: MatchContext) => {
+		return !matcher(ctx);
+	};
+
+export default NegateMatcher;

package/website/matchers/never.ts

@@ -0,0 +1,12 @@
+/**
+ * @title Never
+ * @description Hide from all users
+ * @icon eye-off
+ */
+const MatchNever = () => {
+	return false;
+};
+
+export default MatchNever;
+
+export const cacheable = true;

package/website/matchers/pathname.ts

@@ -0,0 +1,69 @@
+import type { MatchContext } from "../types";
+
+interface BaseCase {
+	/**
+	 * @title Pathname
+	 * @description Must start with "/"
+	 */
+	pathname?: string;
+	/**
+	 * @title Negate
+	 * @description Inverts the match result (NOT)
+	 * @default false
+	 */
+	negate?: boolean;
+}
+
+/** @title Equals */
+interface Equals extends BaseCase {
+	/** @readonly @hide true */
+	type: "Equals";
+}
+
+interface Includes extends BaseCase {
+	/** @readonly @hide true */
+	type: "Includes";
+}
+
+interface Template extends BaseCase {
+	/** @readonly @hide true */
+	type: "Template";
+}
+
+export interface Props {
+	/** @title Operation */
+	case: Equals | Includes | Template;
+}
+
+const operations: Record<Props["case"]["type"], (pathname: string, condition: string) => boolean> =
+	Object.freeze({
+		Equals: (pathname, value) => pathname === value,
+		Includes: (pathname, value) => pathname.includes(value),
+		Template: (pathname, template) => {
+			const escaped = template
+				.replace(/:[^/]+/g, "\0")
+				.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+				.replace(/\0/g, "([^/]+)");
+			const regex = new RegExp(`^${escaped}$`);
+			return regex.test(pathname);
+		},
+	});
+
+/**
+ * @title Pathname
+ * @description Target users based on the pathname
+ * @icon world-www
+ */
+const MatchPathname = (props: Props, { request }: MatchContext) => {
+	const url = new URL(request.url);
+	const pathname = url.pathname;
+	if (!props.case.pathname) {
+		return false;
+	}
+	const result = operations[props.case.type](pathname, props.case.pathname);
+	return props.case.negate ? !result : result;
+};
+
+export default MatchPathname;
+
+export const cacheable = true;

package/website/matchers/queryString.ts

@@ -0,0 +1,98 @@
+import type { MatchContext } from "../types";
+
+interface BaseCase {
+	value: string;
+}
+
+/** @title Equals */
+interface Equals extends BaseCase {
+	/** @readonly @hide true */
+	type: "Equals";
+}
+interface Greater extends BaseCase {
+	/** @readonly @hide true */
+	type: "Greater";
+}
+interface Lesser extends BaseCase {
+	/** @readonly @hide true */
+	type: "Lesser";
+}
+interface GreaterOrEquals extends BaseCase {
+	/** @readonly @hide true */
+	type: "GreaterOrEquals";
+}
+interface LesserOrEquals extends BaseCase {
+	/** @readonly @hide true */
+	type: "LesserOrEquals";
+}
+interface Includes extends BaseCase {
+	/** @readonly @hide true */
+	type: "Includes";
+}
+interface Exists {
+	/** @readonly @hide true */
+	type: "Exists";
+}
+
+/**
+ * @title {{{param}}} {{{case.type}}} {{{case.value}}}
+ */
+interface Condition {
+	param: string;
+	case: Equals | Greater | Lesser | GreaterOrEquals | LesserOrEquals | Includes | Exists;
+}
+
+/**
+ * @title Query String Matcher
+ */
+export interface Props {
+	conditions: Condition[];
+}
+
+const matchesAtLeastOne = (
+	params: string[],
+	condition: Condition,
+	compare: (a: string, b: string) => boolean,
+) => {
+	if (condition.case.type === "Exists") {
+		return false;
+	}
+	const value = (condition.case as BaseCase).value;
+	return params.filter((param) => compare(param, value)).length > 0;
+};
+
+const operations: Record<
+	Condition["case"]["type"],
+	(param: string[], condition: Condition) => boolean
+> = Object.freeze({
+	Equals: (params, condition) => matchesAtLeastOne(params, condition, (a, b) => a === b),
+	Greater: (params, condition) => matchesAtLeastOne(params, condition, (a, b) => a > b),
+	GreaterOrEquals: (params, condition) => matchesAtLeastOne(params, condition, (a, b) => a >= b),
+	Includes: (params, condition) => matchesAtLeastOne(params, condition, (a, b) => a.includes(b)),
+	Lesser: (params, condition) => matchesAtLeastOne(params, condition, (a, b) => a < b),
+	LesserOrEquals: (params, condition) => matchesAtLeastOne(params, condition, (a, b) => a <= b),
+	Exists: (_params, _condition) => true,
+});
+
+/**
+ * @title Query String
+ * @description Match with a specific querystring
+ * @icon question-mark
+ */
+const MatchQueryString = (props: Props, { request }: MatchContext) => {
+	let matches = true;
+	const url = new URL(request.url);
+	for (const condition of props.conditions) {
+		const params = url.searchParams.getAll(condition.param);
+		if (!params.length) {
+			matches = false;
+			continue;
+		}
+		matches = matches && operations[condition.case.type](params, condition);
+	}
+	return matches;
+};
+
+export default MatchQueryString;
+
+export const cacheable = true;

package/website/matchers/random.ts

@@ -0,0 +1,24 @@
+/**
+ * @title ABTest {{{percentage traffic}}}
+ */
+export interface Props {
+	traffic: number;
+}
+
+// once selected the session will reuse the same value
+export const sticky = "session";
+
+/**
+ * @title Random
+ * @description Target a percentage of the total traffic to do an A/B test
+ * @icon arrow-split
+ */
+const MatchRandom = ({ traffic }: Props) => {
+	return Math.random() < traffic;
+};
+
+export default MatchRandom;
+
+export const sessionKey = (props: Props) => {
+	return `${props.traffic}`;
+};

package/website/matchers/site.ts

@@ -0,0 +1,21 @@
+import type { MatchContext } from "../types";
+
+/**
+ * @title {{{siteId}}}
+ */
+export interface Props {
+	siteId: number;
+}
+
+/**
+ * @title Site
+ * @description Target users based on the deco website ID they are on
+ * @icon hand-click
+ */
+const MatchSite = ({ siteId }: Props, { siteId: currSiteId }: MatchContext) => {
+	return siteId === currSiteId;
+};
+
+export default MatchSite;
+
+export const cacheable = true;

package/website/matchers/userAgent.ts

@@ -0,0 +1,23 @@
+import type { MatchContext } from "../types";
+
+/**
+ * @title {{{includes}}} {{{match}}}
+ */
+export interface Props {
+	includes?: string;
+	match?: string;
+}
+
+/**
+ * @title User Agent
+ * @description Target users based on their web browser or operational system
+ * @icon world
+ */
+const MatchUserAgent = ({ includes, match }: Props, { request }: MatchContext) => {
+	const ua = request.headers.get("user-agent") || "";
+	const regexMatch = match ? new RegExp(match).test(ua) : true;
+	const includesFound = includes ? ua.includes(includes) : true;
+	return regexMatch && includesFound;
+};
+
+export default MatchUserAgent;

package/website/mod.ts

@@ -0,0 +1,48 @@
+/**
+ * Website app module — standard autoconfig contract.
+ *
+ * Exports `configure` following the AppModContract pattern.
+ * Provides SEO defaults, theme, matchers, and flags for the site.
+ */
+
+import type { AppDefinition, ResolveSecretFn } from "../commerce/app-types";
+import { configureWebsite } from "./client";
+import manifest from "./manifest.gen";
+import type { WebsiteConfig } from "./types";
+
+// -------------------------------------------------------------------------
+// State
+// -------------------------------------------------------------------------
+
+export interface WebsiteState {
+	config: WebsiteConfig;
+}
+
+// -------------------------------------------------------------------------
+// Configure
+// -------------------------------------------------------------------------
+
+/**
+ * Configure the Website app from CMS block data.
+ * Always returns an AppDefinition (no required fields).
+ */
+export async function configure(
+	// biome-ignore lint/suspicious/noExplicitAny: block data comes from CMS with no fixed schema
+	block: any,
+	_resolveSecret: ResolveSecretFn,
+): Promise<AppDefinition<WebsiteState>> {
+	const config: WebsiteConfig = {
+		seo: block?.seo,
+	};
+
+	configureWebsite(config);
+
+	return {
+		name: "website",
+		manifest,
+		state: { config },
+	};
+}
+
+/** Placeholder preview for CMS editor. */
+export const preview = undefined;

package/website/sections/Analytics/Analytics.tsx

@@ -0,0 +1,7 @@
+import AnalyticsComponent, { type Props } from "../../components/Analytics";
+
+function Section(props: Props) {
+	return <AnalyticsComponent {...props} />;
+}
+
+export default Section;

package/website/sections/Seo/Seo.tsx

@@ -0,0 +1,14 @@
+import SeoComponent, { type Props as SeoProps } from "../../components/Seo";
+
+type Props = Omit<SeoProps, "jsonLDs">;
+
+/**
+ * @deprecated true
+ * @migrate website/sections/Seo/SeoV2.tsx
+ * @title SEO deprecated
+ */
+function Section(props: Props) {
+	return <SeoComponent {...props} />;
+}
+
+export default Section;

package/website/sections/Seo/SeoV2.tsx

@@ -0,0 +1,45 @@
+import SeoComponent, {
+	renderTemplateString,
+	type SEOSection,
+	type Props as SeoProps,
+} from "../../components/Seo";
+import type { WebsiteConfig } from "../../types";
+
+type Props = Pick<
+	SeoProps,
+	"title" | "description" | "type" | "favicon" | "image" | "themeColor" | "noIndexing"
+>;
+
+/**
+ * Loader that merges page-level SEO props with app-level defaults.
+ * The framework calls this with the WebsiteConfig from the app state.
+ */
+export function loader(props: Props, seo?: WebsiteConfig["seo"]) {
+	const {
+		titleTemplate = "",
+		descriptionTemplate = "",
+		title: appTitle = "",
+		description: appDescription = "",
+		...seoSiteProps
+	} = seo ?? {};
+
+	const { title: _title, description: _description, ...seoProps } = props;
+
+	const title = renderTemplateString(
+		(titleTemplate ?? "").trim().length === 0 ? "%s" : titleTemplate,
+		_title ?? appTitle,
+	);
+
+	const description = renderTemplateString(
+		(descriptionTemplate ?? "").trim().length === 0 ? "%s" : descriptionTemplate,
+		_description ?? appDescription,
+	);
+
+	return { ...seoSiteProps, ...seoProps, title, description };
+}
+
+function Section(props: Props): SEOSection {
+	return <SeoComponent {...props} />;
+}
+
+export default Section;

package/website/types.ts

@@ -0,0 +1,125 @@
+/**
+ * Core types for the website app.
+ *
+ * Defines the matcher/flag system types locally so we don't depend on
+ * @deco/deco/blocks — everything is self-contained in @decocms/apps.
+ */
+
+// -------------------------------------------------------------------------
+// Script
+// -------------------------------------------------------------------------
+
+export type Script = { src: string | ((req: Request) => string) };
+
+// -------------------------------------------------------------------------
+// Matcher system
+// -------------------------------------------------------------------------
+
+/**
+ * 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;
+
+// -------------------------------------------------------------------------
+// Flag system
+// -------------------------------------------------------------------------
+
+/**
+ * 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 multivariate flag with multiple variants, each with its own matcher.
+ */
+export interface MultivariateFlag<T> {
+	variants: Variant<T>[];
+}
+
+/**
+ * A single variant in a multivariate flag.
+ */
+export interface Variant<T> {
+	matcher?: Matcher;
+	value: T;
+	weight?: number;
+}
+
+// -------------------------------------------------------------------------
+// Theme / Font types
+// -------------------------------------------------------------------------
+
+export interface Variable {
+	name: string;
+	value: string;
+}
+
+export type Font = {
+	family: string;
+	styleSheet: string;
+};
+
+// -------------------------------------------------------------------------
+// SEO types
+// -------------------------------------------------------------------------
+
+/** @description Recommended: 1200 x 630 px (up to 5MB) */
+export type ImageWidget = string;
+
+export type OGType = "website" | "article";
+
+export interface SeoConfig {
+	title?: string;
+	/**
+	 * @title Title template
+	 * @description add a %s whenever you want it to be replaced with the product name, category name or search term
+	 * @default %s
+	 */
+	titleTemplate?: string;
+	description?: string;
+	/**
+	 * @title Description template
+	 * @description add a %s whenever you want it to be replaced with the product name, category name or search term
+	 * @default %s
+	 */
+	descriptionTemplate?: string;
+	/** @default website */
+	type?: OGType;
+	/** @description Recommended: 1200 x 630 px (up to 5MB) */
+	image?: ImageWidget;
+	/** @description Recommended: 16 x 16 px */
+	favicon?: ImageWidget;
+	/** @description Suggested color that browsers should use to customize the display */
+	themeColor?: string;
+	/**
+	 * @title Disable indexing
+	 * @description In testing, you can use this to prevent search engines from indexing your site
+	 */
+	noIndexing?: boolean;
+}
+
+// -------------------------------------------------------------------------
+// Website app config
+// -------------------------------------------------------------------------
+
+export interface WebsiteConfig {
+	/** @title Seo */
+	seo?: SeoConfig;
+}

package/website/utils/html.ts

@@ -0,0 +1 @@
+export const stripHTML = (str: string) => str.replace(/(<([^>]+)>)/gi, "");

package/website/utils/location.ts

@@ -0,0 +1,20 @@
+export const toRadians = (degrees: number): number => {
+	return degrees * (Math.PI / 180);
+};
+
+export const haversine = (coordinate1: string, coordinate2: string): number => {
+	const [lat1, lng1] = coordinate1.split(",").map((value) => Number(value));
+	const [lat2, lng2] = coordinate2.split(",").map((value) => Number(value));
+
+	const earthRadius = 6371000; // Earth radius in meters
+	const dLat = toRadians(lat1 - lat2);
+	const dLon = toRadians(lng1 - lng2);
+
+	const halfChordLengthSquared =
+		Math.sin(dLat / 2) * Math.sin(dLat / 2) +
+		Math.sin(dLon / 2) * Math.sin(dLon / 2) * Math.cos(toRadians(lat1)) * Math.cos(toRadians(lat2));
+
+	const angularDistance =
+		2 * Math.atan2(Math.sqrt(halfChordLengthSquared), Math.sqrt(1 - halfChordLengthSquared));
+	return earthRadius * angularDistance;
+};