@decocms/apps 0.20.1

package/.github/workflows/release.yml

@@ -0,0 +1,34 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  packages: write
+  issues: write
+  pull-requests: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: https://npm.pkg.github.com
+          scope: "@decocms"
+
+      - run: npm install
+
+      - name: Release
+        run: npx semantic-release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/.releaserc.json

@@ -0,0 +1,25 @@
+{
+  "branches": ["main"],
+  "plugins": [
+    ["@semantic-release/commit-analyzer", {
+      "preset": "angular",
+      "releaseRules": [
+        { "type": "feat", "release": "minor" },
+        { "type": "fix", "release": "patch" },
+        { "type": "perf", "release": "patch" },
+        { "type": "refactor", "release": "patch" },
+        { "type": "docs", "release": false },
+        { "type": "chore", "release": false },
+        { "type": "style", "release": false },
+        { "type": "test", "release": false }
+      ]
+    }],
+    "@semantic-release/release-notes-generator",
+    "@semantic-release/npm",
+    "@semantic-release/github",
+    ["@semantic-release/git", {
+      "assets": ["package.json"],
+      "message": "chore(release): ${nextRelease.version} [skip ci]"
+    }]
+  ]
+}

package/commerce/components/Image.tsx

@@ -0,0 +1,209 @@
+/**
+ * Optimized Image component with CDN-aware transforms.
+ *
+ * Generates responsive srcset, enforces width/height for CLS prevention,
+ * and builds optimized URLs for different image CDNs (VTEX, Shopify,
+ * Deco, Cloudflare).
+ *
+ * @example
+ * ```tsx
+ * <Image
+ *   src="https://store.vteximg.com.br/products/123.jpg"
+ *   width={400}
+ *   height={400}
+ *   alt="Product name"
+ *   cdn="vtex"
+ * />
+ * ```
+ */
+
+import type { ImgHTMLAttributes } from "react";
+
+export type ImageCDN = "vtex" | "shopify" | "deco" | "cloudflare" | "none";
+
+export interface ImageProps extends Omit<ImgHTMLAttributes<HTMLImageElement>, "src" | "width" | "height"> {
+  src: string;
+  width: number;
+  height: number;
+  /** Image CDN to use for URL transforms. @default "none" */
+  cdn?: ImageCDN;
+  /**
+   * Responsive sizes descriptor.
+   * @default "(max-width: 768px) 100vw, 50vw"
+   */
+  sizes?: string;
+  /**
+   * Multipliers for srcset generation.
+   * @default [1, 2]
+   */
+  srcSetMultipliers?: number[];
+  /** Preload the image (adds fetchPriority="high"). */
+  preload?: boolean;
+}
+
+// -------------------------------------------------------------------------
+// CDN URL builders
+// -------------------------------------------------------------------------
+
+function vtexImageUrl(src: string, width: number, height: number): string {
+  if (src.includes("vteximg.com.br") || src.includes("vtexassets.com")) {
+    return src.replace(
+      /(-\d+-\d+)(\.\w+)$/,
+      `-${width}-${height}$2`,
+    );
+  }
+
+  const url = new URL(src, "https://placeholder.com");
+  url.searchParams.set("width", String(width));
+  url.searchParams.set("height", String(height));
+  return url.toString();
+}
+
+function shopifyImageUrl(src: string, width: number): string {
+  if (src.includes("cdn.shopify.com")) {
+    return src.replace(/(\.\w+)(\?.*)?$/, `_${width}x$1$2`);
+  }
+  return src;
+}
+
+function decoImageUrl(src: string, width: number, height: number): string {
+  if (src.includes("decocache.com") || src.includes("ozksgdmyrqcxcwhnbepg")) {
+    const url = new URL(src);
+    url.searchParams.set("width", String(width));
+    url.searchParams.set("height", String(height));
+    url.searchParams.set("fit", "cover");
+    return url.toString();
+  }
+  return src;
+}
+
+function cloudflareImageUrl(src: string, width: number, height: number): string {
+  return `/cdn-cgi/image/width=${width},height=${height},fit=cover,format=auto,quality=80/${src}`;
+}
+
+function buildUrl(src: string, width: number, height: number, cdn: ImageCDN): string {
+  switch (cdn) {
+    case "vtex": return vtexImageUrl(src, width, height);
+    case "shopify": return shopifyImageUrl(src, width);
+    case "deco": return decoImageUrl(src, width, height);
+    case "cloudflare": return cloudflareImageUrl(src, width, height);
+    default: return src;
+  }
+}
+
+function buildSrcSet(
+  src: string,
+  width: number,
+  height: number,
+  cdn: ImageCDN,
+  multipliers: number[],
+): string {
+  return multipliers
+    .map((m) => {
+      const w = Math.round(width * m);
+      const h = Math.round(height * m);
+      return `${buildUrl(src, w, h, cdn)} ${w}w`;
+    })
+    .join(", ");
+}
+
+// -------------------------------------------------------------------------
+// Component
+// -------------------------------------------------------------------------
+
+export function Image({
+  src,
+  width,
+  height,
+  cdn = "none",
+  sizes = "(max-width: 768px) 100vw, 50vw",
+  srcSetMultipliers = [1, 2],
+  preload,
+  loading,
+  decoding,
+  ...rest
+}: ImageProps) {
+  const optimizedSrc = buildUrl(src, width, height, cdn);
+  const srcSet = cdn !== "none"
+    ? buildSrcSet(src, width, height, cdn, srcSetMultipliers)
+    : undefined;
+
+  return (
+    <img
+      src={optimizedSrc}
+      srcSet={srcSet}
+      sizes={srcSet ? sizes : undefined}
+      width={width}
+      height={height}
+      loading={loading ?? (preload ? "eager" : "lazy")}
+      decoding={decoding ?? "async"}
+      fetchPriority={preload ? "high" : undefined}
+      {...rest}
+    />
+  );
+}
+
+// -------------------------------------------------------------------------
+// Picture (responsive art direction)
+// -------------------------------------------------------------------------
+
+export interface PictureSource {
+  src: string;
+  width: number;
+  height: number;
+  media: string;
+  cdn?: ImageCDN;
+}
+
+export interface PictureProps extends Omit<ImageProps, "sizes"> {
+  sources: PictureSource[];
+}
+
+/**
+ * Picture component for responsive art direction.
+ *
+ * @example
+ * ```tsx
+ * <Picture
+ *   sources={[
+ *     { src: mobileSrc, width: 375, height: 200, media: "(max-width: 767px)", cdn: "vtex" },
+ *     { src: desktopSrc, width: 1200, height: 400, media: "(min-width: 768px)", cdn: "vtex" },
+ *   ]}
+ *   src={desktopSrc}
+ *   width={1200}
+ *   height={400}
+ *   alt="Banner"
+ * />
+ * ```
+ */
+export function Picture({
+  sources,
+  src,
+  width,
+  height,
+  cdn = "none",
+  preload,
+  ...rest
+}: PictureProps) {
+  return (
+    <picture>
+      {sources.map((source, i) => (
+        <source
+          key={i}
+          srcSet={buildUrl(source.src, source.width, source.height, source.cdn ?? cdn)}
+          media={source.media}
+          width={source.width}
+          height={source.height}
+        />
+      ))}
+      <Image
+        src={src}
+        width={width}
+        height={height}
+        cdn={cdn}
+        preload={preload}
+        {...rest}
+      />
+    </picture>
+  );
+}

package/commerce/components/JsonLd.tsx

@@ -0,0 +1,285 @@
+/**
+ * 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/apps/commerce/components/JsonLd";
+ *
+ * // In a PDP route
+ * <ProductJsonLd product={product} />
+ *
+ * // In a PLP route
+ * <PLPJsonLd page={productListingPage} />
+ *
+ * // Anywhere with breadcrumbs
+ * <BreadcrumbJsonLd breadcrumb={breadcrumbList} />
+ * ```
+ */
+
+import type {
+  Product,
+  ProductListingPage,
+  BreadcrumbList,
+  ListItem,
+  Offer,
+  AggregateOffer,
+  UnitPriceSpecification,
+  AggregateRating,
+} from "../types/commerce";
+
+// -------------------------------------------------------------------------
+// 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: Product;
+  /** Override the canonical URL. Defaults to product.url. */
+  url?: string;
+}
+
+function getBestOffer(offers: Offer[] | AggregateOffer | 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 AggregateOffer;
+    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: UnitPriceSpecification[] | 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 as Offer[] | AggregateOffer | undefined);
+  const images = product.image?.map((img) => img.url).filter(Boolean) ?? [];
+  const rating = product.aggregateRating as AggregateRating | undefined;
+
+  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 && 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: ProductListingPage;
+  /** Override the canonical URL. */
+  url?: string;
+}
+
+export function PLPJsonLd({ page, url }: PLPJsonLdProps) {
+  const items = (page.products ?? []).map((product, index) => {
+    const offer = getBestOffer(product.offers as Offer[] | AggregateOffer | undefined);
+    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: BreadcrumbList;
+}
+
+export function BreadcrumbJsonLd({ breadcrumb }: BreadcrumbJsonLdProps) {
+  const items = (breadcrumb.itemListElement ?? []).map((item, index) => {
+    const listItem = item as ListItem;
+    return {
+      "@type": "ListItem" as const,
+      position: listItem.position ?? index + 1,
+      name: listItem.name,
+      item: listItem.item ?? listItem.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/commerce/sdk/analytics.ts

@@ -0,0 +1,24 @@
+import type { AnalyticsEvent } from "../types/commerce";
+
+declare global {
+  interface Window {
+    DECO: { events: { dispatch: (event: any) => void } };
+    DECO_SITES_STD: {
+      sendAnalyticsEvent: (args: AnalyticsEvent) => void;
+    };
+  }
+}
+
+export const sendEvent = <E extends AnalyticsEvent>(event: E) => {
+  if (typeof globalThis.window?.DECO?.events?.dispatch === "function") {
+    globalThis.window.DECO.events.dispatch(event);
+    return;
+  }
+
+  if (typeof globalThis.window?.DECO_SITES_STD?.sendAnalyticsEvent === "function") {
+    globalThis.window.DECO_SITES_STD.sendAnalyticsEvent(event);
+    return;
+  }
+
+  console.info("[analytics] No event dispatcher found. Event not sent:", event.name);
+};

package/commerce/sdk/formatPrice.ts

@@ -0,0 +1,23 @@
+const formatters = new Map<string, Intl.NumberFormat>();
+
+const formatter = (currency: string, locale: string) => {
+  const key = `${currency}::${locale}`;
+
+  if (!formatters.has(key)) {
+    formatters.set(
+      key,
+      new Intl.NumberFormat(locale, {
+        style: "currency",
+        currency,
+      }),
+    );
+  }
+
+  return formatters.get(key)!;
+};
+
+export const formatPrice = (
+  price: number | undefined,
+  currency = "BRL",
+  locale = "pt-BR",
+) => price ? formatter(currency, locale).format(price) : null;

package/commerce/sdk/url.ts

@@ -0,0 +1,9 @@
+export const relative = (link?: string | undefined) => {
+  if (!link) return undefined;
+  try {
+    const linkUrl = new URL(link, "https://localhost");
+    return `${linkUrl.pathname}${linkUrl.search}`;
+  } catch {
+    return link;
+  }
+};

package/commerce/sdk/useOffer.ts

@@ -0,0 +1,75 @@
+import type {
+  AggregateOffer,
+  UnitPriceSpecification,
+} from "../types/commerce";
+
+const bestInstallment = (
+  acc: UnitPriceSpecification | null,
+  curr: UnitPriceSpecification,
+) => {
+  if (curr.priceComponentType !== "https://schema.org/Installment") {
+    return acc;
+  }
+
+  if (!acc) {
+    return curr;
+  }
+
+  if (acc.price > curr.price) {
+    return curr;
+  }
+
+  if (acc.price < curr.price) {
+    return acc;
+  }
+
+  if (
+    acc.billingDuration && curr.billingDuration &&
+    acc.billingDuration < curr.billingDuration
+  ) {
+    return curr;
+  }
+
+  return acc;
+};
+
+const installmentToString = (
+  installment: UnitPriceSpecification,
+  locale = "pt-BR",
+  currency = "BRL",
+) => {
+  const { billingDuration, billingIncrement } = installment;
+
+  if (!billingDuration || !billingIncrement) {
+    return "";
+  }
+
+  const formatted = new Intl.NumberFormat(locale, {
+    style: "currency",
+    currency,
+  }).format(billingIncrement);
+
+  return `${billingDuration}x ${formatted}`;
+};
+
+export const useOffer = (aggregateOffer?: AggregateOffer) => {
+  const offer = aggregateOffer?.offers?.[0];
+  const listPrice = offer?.priceSpecification?.find((spec) =>
+    spec.priceType === "https://schema.org/ListPrice"
+  );
+  const installment = offer?.priceSpecification?.reduce(bestInstallment, null);
+  const seller = offer?.seller;
+  const price = offer?.price;
+  const availability = offer?.availability;
+
+  return {
+    price,
+    listPrice: listPrice?.price,
+    availability,
+    seller,
+    installments: installment && price
+      ? installmentToString(installment)
+      : null,
+    installment,
+  };
+};