@decocms/blocks 7.1.2 → 7.2.1

package/src/hooks/Image.tsx

@@ -0,0 +1,250 @@
+import type { ImgHTMLAttributes } from "react";
+import { forwardRef } from "react";
+
+// -------------------------------------------------------------------------
+// Known asset prefixes that get stripped to produce a relative src path
+// -------------------------------------------------------------------------
+
+const DECO_CACHE_URL = "https://assets.decocache.com/";
+const S3_URL = "https://deco-sites-assets.s3.sa-east-1.amazonaws.com/";
+
+// -------------------------------------------------------------------------
+// Configurable CDN domain
+// -------------------------------------------------------------------------
+
+let imageCdnDomain = "decoims.com";
+
+/**
+ * Register the image CDN domain used by `getOptimizedMediaUrl`.
+ * Call once in your site's setup.ts before any page loads.
+ *
+ * Available domains:
+ * - `decoims.com` (Cloudflare, default — best compression, same edge as Workers)
+ * - `deco-assets.edgedeco.com` (Azion IMS)
+ * - `deco-assets.decoazn.com` (Azion IMS, legacy)
+ */
+export function registerImageCdnDomain(domain: string) {
+	imageCdnDomain = domain.replace(/^https?:\/\//, "").replace(/\/+$/, "");
+}
+
+export function getImageCdnDomain(): string {
+	return imageCdnDomain;
+}
+
+// -------------------------------------------------------------------------
+// Fit options & optimization types
+// -------------------------------------------------------------------------
+
+export type FitOptions = "contain" | "cover" | "fill";
+
+export const FACTORS = [1, 2];
+
+interface OptimizationOptions {
+	originalSrc: string;
+	width: number;
+	height?: number;
+	fit: FitOptions;
+}
+
+// -------------------------------------------------------------------------
+// Platform-specific URL optimizers (fallbacks when the CDN can handle
+// the native platform's resize syntax directly)
+// -------------------------------------------------------------------------
+
+function optimizeVTEX(originalSrc: string, width: number, height?: number): string {
+	const src = new URL(originalSrc);
+	const [slash, arquivos, ids, rawId, ...rest] = src.pathname.split("/");
+	const [trueId] = rawId.split("-");
+
+	src.pathname = [slash, arquivos, ids, `${trueId}-${width}-${height ?? width}`, ...rest].join("/");
+
+	return src.href;
+}
+
+function optimizeShopify(originalSrc: string, width: number, height?: number): string {
+	const url = new URL(originalSrc);
+	url.searchParams.set("width", `${width}`);
+	if (height) url.searchParams.set("height", `${height}`);
+	url.searchParams.set("crop", "center");
+	return url.href;
+}
+
+// -------------------------------------------------------------------------
+// Core optimization function
+// Ported from deco-cx/apps website/components/Image.tsx
+// -------------------------------------------------------------------------
+
+/**
+ * Builds an optimized image URL.
+ *
+ * For Deco-hosted images (decocache / S3), strips the known prefix and
+ * routes through the Deco image CDN for edge resize + format conversion.
+ *
+ * For platform-specific images (VTEX, Shopify), rewrites the URL using
+ * the platform's native resize params — no CDN proxy needed.
+ *
+ * Data URIs are returned as-is.
+ */
+export function getOptimizedMediaUrl(opts: OptimizationOptions): string {
+	const { originalSrc, width, height, fit } = opts;
+
+	// Defensive: an upstream CMS payload occasionally has missing/null image
+	// fields. Crashing the entire React tree on `undefined.startsWith` would
+	// take down the whole page. Return an empty string so the resulting
+	// `<img>` is rendered with no src — the browser shows the broken-image
+	// placeholder and SSR completes cleanly.
+	if (typeof originalSrc !== "string" || originalSrc.length === 0) {
+		if (typeof process !== "undefined" && process.env?.NODE_ENV !== "production") {
+			console.warn(
+				`[Image] getOptimizedMediaUrl called with empty/undefined src — rendering empty src instead of crashing.`,
+			);
+		}
+		return "";
+	}
+
+	if (originalSrc.startsWith("data:")) {
+		return originalSrc;
+	}
+
+	if (/(vteximg\.com\.br|vtexassets\.com|myvtex\.com)\/arquivos\/ids\/\d+/.test(originalSrc)) {
+		return optimizeVTEX(originalSrc, width, height);
+	}
+
+	if (originalSrc.startsWith("https://cdn.shopify.com")) {
+		return optimizeShopify(originalSrc, width, height);
+	}
+
+	let imageSource = originalSrc.replace(DECO_CACHE_URL, "").replace(S3_URL, "").split("?")[0];
+
+	// Already on the image CDN — strip the host so we don't proxy through ourselves.
+	const cdnPrefix = `https://${imageCdnDomain}/`;
+	if (imageSource.startsWith(cdnPrefix)) {
+		imageSource = imageSource.slice(cdnPrefix.length);
+	}
+
+	const params = new URLSearchParams();
+	params.set("fit", fit);
+	params.set("width", `${width}`);
+	if (height) params.set("height", `${height}`);
+
+	return `https://${imageCdnDomain}/image?${params}&src=${imageSource}`;
+}
+
+/**
+ * Generates a srcset string with responsive multipliers.
+ */
+export function getSrcSet(
+	originalSrc: string,
+	width: number,
+	height?: number,
+	fit?: FitOptions,
+	factors: number[] = FACTORS,
+): string | undefined {
+	if (typeof originalSrc !== "string" || originalSrc.length === 0) {
+		return undefined;
+	}
+
+	const entries: string[] = [];
+
+	for (const factor of factors) {
+		const w = Math.trunc(factor * width);
+		const h = height ? Math.trunc(factor * height) : undefined;
+
+		const src = getOptimizedMediaUrl({
+			originalSrc,
+			width: w,
+			height: h,
+			fit: fit ?? "cover",
+		});
+
+		if (src) {
+			entries.push(`${src} ${w}w`);
+		}
+	}
+
+	return entries.length > 0 ? entries.join(", ") : undefined;
+}
+
+// -------------------------------------------------------------------------
+// Image component
+// -------------------------------------------------------------------------
+
+export interface ImageProps
+	extends Omit<ImgHTMLAttributes<HTMLImageElement>, "src" | "width" | "height"> {
+	src: string;
+	/** @description Improves Web Vitals (CLS/LCP) */
+	width: number;
+	/** @description Improves Web Vitals (CLS/LCP) */
+	height?: number;
+	/** @description Object-fit */
+	fit?: FitOptions;
+	/**
+	 * @description Web Vitals (LCP). Injects a `<link rel="preload">` tag
+	 * alongside the `<img>`, sets `fetchPriority="high"` and `loading="eager"`.
+	 * Use once per page for the LCP image.
+	 */
+	preload?: boolean;
+	/** @description Media query for responsive preloading (e.g. "(min-width: 768px)") */
+	media?: string;
+}
+
+export const Image = forwardRef<HTMLImageElement, ImageProps>(function Image(
+	{
+		src,
+		width,
+		height,
+		fit = "cover",
+		preload,
+		media,
+		loading,
+		decoding,
+		srcSet: srcSetProp,
+		sizes,
+		fetchPriority,
+		...rest
+	},
+	ref,
+) {
+	if (!height && typeof process !== "undefined") {
+		console.warn(`Missing height. This image will NOT be optimized: ${src}`);
+	}
+
+	const optimizedSrc = getOptimizedMediaUrl({
+		originalSrc: src,
+		width,
+		height,
+		fit,
+	});
+	const srcSet = srcSetProp ?? getSrcSet(src, width, height, fit);
+	const resolvedSizes = srcSet ? (sizes ?? "(max-width: 768px) 100vw, 50vw") : undefined;
+
+	return (
+		<>
+			{preload && (
+				<link
+					as="image"
+					rel="preload"
+					href={optimizedSrc}
+					imageSrcSet={srcSet}
+					imageSizes={resolvedSizes}
+					fetchPriority={fetchPriority ?? "high"}
+					media={media}
+				/>
+			)}
+			<img
+				{...rest}
+				src={optimizedSrc}
+				srcSet={srcSet}
+				sizes={resolvedSizes}
+				width={width}
+				height={height}
+				loading={loading ?? (preload ? "eager" : "lazy")}
+				decoding={decoding ?? "async"}
+				fetchPriority={preload ? "high" : fetchPriority}
+				ref={ref}
+			/>
+		</>
+	);
+});
+
+export default Image;

package/src/hooks/JsonLd.tsx

@@ -0,0 +1,353 @@
+/**
+ * SEO JSON-LD structured data components.
+ *
+ * Generates JSON-LD script tags for Product (PDP), ProductList (PLP),
+ * and BreadcrumbList schemas. Compatible with Google's Rich Results
+ * requirements.
+ *
+ * @example
+ * ```tsx
+ * import { ProductJsonLd, PLPJsonLd, BreadcrumbJsonLd } from "@decocms/blocks/hooks";
+ *
+ * // In a PDP route
+ * <ProductJsonLd product={product} />
+ *
+ * // In a PLP route
+ * <PLPJsonLd page={productListingPage} />
+ *
+ * // Anywhere with breadcrumbs
+ * <BreadcrumbJsonLd breadcrumb={breadcrumbList} />
+ * ```
+ *
+ * Type note: originally these components imported `Product`,
+ * `ProductListingPage`, `BreadcrumbList`, etc. from apps-start's
+ * commerce types module (now `@decocms/apps-commerce/types`).
+ * `@decocms/blocks` must not depend on any `apps-*` package (one-way
+ * dependency rule: `apps-*` depends on `blocks`, never the reverse), so
+ * that import can't carry over as-is. Each function here only reads a
+ * small, flat subset of the full schema.org Product/Offer/ListItem
+ * graph (the original code already didn't fully trust the nominal
+ * `Product.offers` type either — see the `as Offer[] | AggregateOffer`
+ * casts it used). The types below are local, minimal, structural
+ * equivalents of just that subset: any commerce `Product` /
+ * `ProductListingPage` / `BreadcrumbList` value is a structural
+ * superset and can be passed in directly without a cast.
+ */
+
+// -------------------------------------------------------------------------
+// Minimal structural types (see file header for why these aren't imported
+// from @decocms/apps-commerce/types)
+// -------------------------------------------------------------------------
+
+interface JsonLdOffer {
+	price?: number;
+	priceCurrency?: string;
+	availability?: string;
+	seller?: string;
+	priceValidUntil?: string;
+}
+
+interface JsonLdAggregateOffer {
+	"@type"?: string;
+	lowPrice?: number;
+	priceCurrency?: string;
+}
+
+interface JsonLdPriceSpecification {
+	priceType?: string;
+	price?: number;
+}
+
+interface JsonLdAggregateRating {
+	ratingValue?: number;
+	reviewCount?: number;
+	ratingCount?: number;
+	bestRating?: number;
+	worstRating?: number;
+}
+
+interface JsonLdImage {
+	url?: string;
+}
+
+interface JsonLdBrand {
+	name?: string;
+}
+
+export interface JsonLdProduct {
+	name?: string;
+	description?: string;
+	url?: string;
+	sku?: string;
+	productID?: string;
+	gtin?: string;
+	brand?: JsonLdBrand | null;
+	image?: JsonLdImage[] | null;
+	offers?: JsonLdOffer[] | JsonLdAggregateOffer;
+	aggregateRating?: JsonLdAggregateRating;
+}
+
+interface JsonLdSeo {
+	canonical?: string;
+	title?: string;
+	description?: string;
+}
+
+export interface JsonLdProductListingPage {
+	products?: JsonLdProduct[];
+	seo?: JsonLdSeo | null;
+}
+
+interface JsonLdListItem {
+	position?: number;
+	name?: string;
+	item?: string;
+	url?: string;
+}
+
+export interface JsonLdBreadcrumbList {
+	itemListElement?: JsonLdListItem[];
+}
+
+// -------------------------------------------------------------------------
+// JSON-LD script renderer
+// -------------------------------------------------------------------------
+
+function JsonLdScript({ data }: { data: unknown }) {
+	return (
+		<script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(data) }} />
+	);
+}
+
+// -------------------------------------------------------------------------
+// Product (PDP)
+// -------------------------------------------------------------------------
+
+export interface ProductJsonLdProps {
+	product: JsonLdProduct;
+	/** Override the canonical URL. Defaults to product.url. */
+	url?: string;
+}
+
+function getBestOffer(offers: JsonLdOffer[] | JsonLdAggregateOffer | undefined): {
+	price?: number;
+	priceCurrency?: string;
+	availability?: string;
+	seller?: string;
+	priceValidUntil?: string;
+} {
+	if (!offers) return {};
+
+	if ("@type" in offers && offers["@type"] === "AggregateOffer") {
+		const agg = offers as JsonLdAggregateOffer;
+		return {
+			price: agg.lowPrice,
+			priceCurrency: agg.priceCurrency,
+		};
+	}
+
+	if (Array.isArray(offers) && offers.length > 0) {
+		const best = offers.reduce((a, b) => {
+			const ap = a.price ?? Infinity;
+			const bp = b.price ?? Infinity;
+			return ap <= bp ? a : b;
+		});
+		return {
+			price: best.price,
+			priceCurrency: best.priceCurrency,
+			availability: best.availability,
+			seller: best.seller,
+			priceValidUntil: best.priceValidUntil,
+		};
+	}
+
+	return {};
+}
+
+function _getListPrice(priceSpec: JsonLdPriceSpecification[] | undefined): number | undefined {
+	if (!priceSpec) return undefined;
+	const list = priceSpec.find(
+		(p) =>
+			p.priceType === "https://schema.org/ListPrice" || p.priceType === "https://schema.org/SRP",
+	);
+	return list?.price;
+}
+
+export function ProductJsonLd({ product, url }: ProductJsonLdProps) {
+	const offer = getBestOffer(product.offers);
+	const images = product.image?.map((img) => img.url).filter(Boolean) ?? [];
+	const rating = product.aggregateRating;
+
+	const data: Record<string, unknown> = {
+		"@context": "https://schema.org",
+		"@type": "Product",
+		name: product.name,
+		description: product.description,
+		image: images.length === 1 ? images[0] : images,
+		url: url ?? product.url,
+		sku: product.sku,
+		productID: product.productID,
+		brand: product.brand ? { "@type": "Brand", name: product.brand.name } : undefined,
+		gtin: product.gtin,
+	};
+
+	if (offer.price != null) {
+		data.offers = {
+			"@type": "Offer",
+			price: offer.price,
+			priceCurrency: offer.priceCurrency ?? "BRL",
+			availability: offer.availability ?? "https://schema.org/InStock",
+			seller: offer.seller ? { "@type": "Organization", name: offer.seller } : undefined,
+			priceValidUntil: offer.priceValidUntil,
+			url: url ?? product.url,
+		};
+	}
+
+	if (rating?.ratingValue) {
+		data.aggregateRating = {
+			"@type": "AggregateRating",
+			ratingValue: rating.ratingValue,
+			reviewCount: rating.reviewCount ?? rating.ratingCount ?? 0,
+			bestRating: rating.bestRating ?? 5,
+			worstRating: rating.worstRating ?? 1,
+		};
+	}
+
+	return <JsonLdScript data={data} />;
+}
+
+// -------------------------------------------------------------------------
+// Product Listing Page (PLP)
+// -------------------------------------------------------------------------
+
+export interface PLPJsonLdProps {
+	page: JsonLdProductListingPage;
+	/** Override the canonical URL. */
+	url?: string;
+}
+
+export function PLPJsonLd({ page, url }: PLPJsonLdProps) {
+	const items = (page.products ?? []).map((product, index) => {
+		const offer = getBestOffer(product.offers);
+		return {
+			"@type": "ListItem" as const,
+			position: index + 1,
+			item: {
+				"@type": "Product" as const,
+				name: product.name,
+				url: product.url,
+				image: product.image?.[0]?.url,
+				offers:
+					offer.price != null
+						? {
+								"@type": "Offer" as const,
+								price: offer.price,
+								priceCurrency: offer.priceCurrency ?? "BRL",
+								availability: offer.availability ?? "https://schema.org/InStock",
+							}
+						: undefined,
+			},
+		};
+	});
+
+	const data = {
+		"@context": "https://schema.org",
+		"@type": "ItemList",
+		url: url ?? page.seo?.canonical,
+		name: page.seo?.title,
+		description: page.seo?.description,
+		numberOfItems: page.products?.length ?? 0,
+		itemListElement: items,
+	};
+
+	return <JsonLdScript data={data} />;
+}
+
+// -------------------------------------------------------------------------
+// Breadcrumb
+// -------------------------------------------------------------------------
+
+export interface BreadcrumbJsonLdProps {
+	breadcrumb: JsonLdBreadcrumbList;
+}
+
+export function BreadcrumbJsonLd({ breadcrumb }: BreadcrumbJsonLdProps) {
+	const items = (breadcrumb.itemListElement ?? []).map((item, index) => {
+		return {
+			"@type": "ListItem" as const,
+			position: item.position ?? index + 1,
+			name: item.name,
+			item: item.item ?? item.url,
+		};
+	});
+
+	const data = {
+		"@context": "https://schema.org",
+		"@type": "BreadcrumbList",
+		itemListElement: items,
+		numberOfItems: items.length,
+	};
+
+	return <JsonLdScript data={data} />;
+}
+
+// -------------------------------------------------------------------------
+// Generic SEO Meta
+// -------------------------------------------------------------------------
+
+export interface SeoMetaProps {
+	title?: string;
+	description?: string;
+	canonical?: string;
+	image?: string;
+	noIndex?: boolean;
+	type?: "website" | "article" | "product";
+	siteName?: string;
+}
+
+/**
+ * Generates Open Graph and Twitter Card meta tags.
+ *
+ * Use this in combination with TanStack Router's `meta()` route option,
+ * or render directly in the component tree (tags will be hoisted to <head>
+ * by React's built-in behavior with TanStack Start).
+ */
+export function seoMetaTags(props: SeoMetaProps): Array<Record<string, string>> {
+	const tags: Array<Record<string, string>> = [];
+
+	if (props.title) {
+		tags.push({ title: props.title });
+		tags.push({ property: "og:title", content: props.title });
+		tags.push({ name: "twitter:title", content: props.title });
+	}
+
+	if (props.description) {
+		tags.push({ name: "description", content: props.description });
+		tags.push({ property: "og:description", content: props.description });
+		tags.push({ name: "twitter:description", content: props.description });
+	}
+
+	if (props.canonical) {
+		tags.push({ property: "og:url", content: props.canonical });
+	}
+
+	if (props.image) {
+		tags.push({ property: "og:image", content: props.image });
+		tags.push({ name: "twitter:image", content: props.image });
+		tags.push({ name: "twitter:card", content: "summary_large_image" });
+	}
+
+	if (props.type) {
+		tags.push({ property: "og:type", content: props.type });
+	}
+
+	if (props.siteName) {
+		tags.push({ property: "og:site_name", content: props.siteName });
+	}
+
+	if (props.noIndex) {
+		tags.push({ name: "robots", content: "noindex, nofollow" });
+	}
+
+	return tags;
+}

package/src/hooks/Picture.tsx

@@ -0,0 +1,104 @@
+import {
+	type ComponentPropsWithoutRef,
+	createContext,
+	forwardRef,
+	type ReactNode,
+	useContext,
+	useMemo,
+} from "react";
+import { type FitOptions, getOptimizedMediaUrl, getSrcSet } from "./Image";
+
+// -------------------------------------------------------------------------
+// Preload context — flows from <Picture preload> to child <Source> elements
+// so each source can inject its own <link rel="preload"> with the correct
+// media query for responsive art direction.
+// -------------------------------------------------------------------------
+
+interface PreloadContextValue {
+	preload: boolean;
+}
+
+const PreloadContext = createContext<PreloadContextValue>({ preload: false });
+
+// -------------------------------------------------------------------------
+// Source — composable <source> with automatic srcSet optimization and
+// preload link injection when inside a <Picture preload>.
+// -------------------------------------------------------------------------
+
+export type SourceProps = Omit<ComponentPropsWithoutRef<"source">, "width" | "height"> & {
+	src: string;
+	/** @description Improves Web Vitals (CLS|LCP) */
+	width: number;
+	/** @description Improves Web Vitals (CLS|LCP) */
+	height?: number;
+	/** @description Improves Web Vitals (LCP). Use high for LCP image. */
+	fetchPriority?: "high" | "low" | "auto";
+	/** @description Object-fit */
+	fit?: FitOptions;
+};
+
+export const Source = forwardRef<HTMLSourceElement, SourceProps>(function Source(
+	{ src, width, height, fetchPriority, fit = "cover", ...rest },
+	ref,
+) {
+	const { preload } = useContext(PreloadContext);
+
+	const optimizedSrc = getOptimizedMediaUrl({
+		originalSrc: src,
+		width,
+		height,
+		fit,
+	});
+	const srcSet = rest.srcSet ?? getSrcSet(src, width, height, fit);
+
+	return (
+		<>
+			{preload && (
+				<link
+					as="image"
+					rel="preload"
+					href={optimizedSrc}
+					imageSrcSet={srcSet}
+					fetchPriority={fetchPriority ?? "high"}
+					media={rest.media}
+				/>
+			)}
+			<source {...rest} srcSet={srcSet ?? optimizedSrc} width={width} height={height} ref={ref} />
+		</>
+	);
+});
+
+// -------------------------------------------------------------------------
+// Picture — composable wrapper that provides preload context to children.
+//
+// Usage:
+//   <Picture preload={isLcp}>
+//     <Source media="(max-width: 767px)" src={mobile} width={320} height={280} />
+//     <Source media="(min-width: 768px)" src={desktop} width={1280} height={280} />
+//     <Image src={desktop} width={1280} height={280} />
+//   </Picture>
+// -------------------------------------------------------------------------
+
+export type PictureProps = ComponentPropsWithoutRef<"picture"> & {
+	children: ReactNode;
+	/**
+	 * @description When true, child <Source> and <Image> elements inject
+	 * `<link rel="preload">` tags for their respective media queries.
+	 */
+	preload?: boolean;
+};
+
+export const Picture = forwardRef<HTMLPictureElement, PictureProps>(function Picture(
+	{ children, preload = false, ...props },
+	ref,
+) {
+	const value = useMemo(() => ({ preload }), [preload]);
+
+	return (
+		<PreloadContext.Provider value={value}>
+			<picture {...props} ref={ref}>
+				{children}
+			</picture>
+		</PreloadContext.Provider>
+	);
+});