@wocart/storefront 1.21.0 → 1.22.0

package/CHANGELOG.md

@@ -5,6 +5,26 @@ follows [semantic versioning](https://semver.org/): breaking changes ship only
 in a new major version, and an export is marked `@deprecated` for at least one
 minor release before a major removes it.
 
+## 1.22.0 — 2026-10-24
+
+What moving Theme-00 onto the SDK showed every theme needs: an add reported
+as what it put in, one canonical address per page, and product descriptions
+read the same for legacy rows.
+
+### Added
+
+- `addedLines(before, after)`: what an add put in the basket — each line that
+  grew, by what it grew — for an `AddToCart` event that reports the add, not
+  the whole basket; empty when the basket had no room.
+- `canonicalUrl(origin, { pathname, locale, routing }, search)`: a page's
+  canonical address — its path in its language, keeping only the listing page
+  (`?page=2`), never an order, a search, a coupon or an ad's click id.
+
+### Fixed
+
+- `productMeta` reads an empty `descriptionPlain` as no plain text: a legacy
+  text row is then described by its own text, as before plain text existed.
+
 ## 1.21.0 — 2026-10-24
 
 ### Added

package/USAGE.md

@@ -716,12 +716,23 @@ script:
 
 ~~~astro
 ---
-import { jsonLd, productMeta, productStructuredData } from "@wocart/storefront";
+import { canonicalUrl, jsonLd, productMeta, productStructuredData } from "@wocart/storefront";
 const meta = productMeta(product);
+const canonical = canonicalUrl(Astro.url.origin, store, Astro.url.search);
 ---
 <title>{meta.title} | {store.config.name}</title>
 {meta.description && <meta name="description" content={meta.description} />}
-<script type="application/ld+json" set:html={jsonLd(productStructuredData(product, { url: Astro.url.href, storeName: store.config.name }))} />
+<script type="application/ld+json" set:html={jsonLd(productStructuredData(product, { url: canonical, storeName: store.config.name }))} />
+~~~
+
+Every page's `<link rel="canonical">` is `canonicalUrl(origin, { pathname,
+locale, routing }, search)`: the page's path in its language, keeping only the
+listing page it shows (`?page=2`). An order, a search, a coupon or an ad's
+click id (`fbclid`, `utm_*`) in the address is the same page to a search
+engine; a canonical that kept them would split one page into many.
+
+~~~ts
+const canonical = canonicalUrl(Astro.url.origin, store, Astro.url.search);
 ~~~
 
 ### Product lists
@@ -1190,6 +1201,17 @@ basket.addSelections(
 );
 ~~~
 
+What an add put in the basket is `addedLines(before, after)`: each line that
+grew, by what it grew. Report that as the `AddToCart` event — never the whole
+basket — and read an empty answer as a basket with no room left.
+
+~~~ts
+const before = basket.getLines();
+const added = addedLines(before, basket.addSelections(line, selections));
+if (added.length === 0) showBasketFull();
+else tracker.track("AddToCart", buildMetaAddToCartPayload(added));
+~~~
+
 ### Single-product order versus basket order
 
 An order is either:

package/dist/basket.d.ts

@@ -95,3 +95,17 @@ export declare function toOrderItems(lines: readonly BasketLine[]): BasketLineIn
  * Create a deep Basket Store.
  */
 export declare function createBasketStore(options?: BasketStoreOptions): BasketStore;
+/**
+ * What an add put in the basket: each line of `after` whose quantity grew
+ * since `before`, with the quantity it grew by — what an `AddToCart` event
+ * reports, never the whole basket. Empty when nothing went in, as when the
+ * basket was full.
+ *
+ * ```ts
+ * const before = basket.getLines();
+ * const added = addedLines(before, basket.addSelections(line, selections));
+ * if (added.length === 0) showBasketFull();
+ * else tracker.track("AddToCart", buildMetaAddToCartPayload(added));
+ * ```
+ */
+export declare function addedLines(before: readonly BasketLine[], after: readonly BasketLine[]): BasketLine[];

package/dist/basket.js

@@ -277,3 +277,23 @@ export function createBasketStore(options = {}) {
         },
     };
 }
+/**
+ * What an add put in the basket: each line of `after` whose quantity grew
+ * since `before`, with the quantity it grew by — what an `AddToCart` event
+ * reports, never the whole basket. Empty when nothing went in, as when the
+ * basket was full.
+ *
+ * ```ts
+ * const before = basket.getLines();
+ * const added = addedLines(before, basket.addSelections(line, selections));
+ * if (added.length === 0) showBasketFull();
+ * else tracker.track("AddToCart", buildMetaAddToCartPayload(added));
+ * ```
+ */
+export function addedLines(before, after) {
+    const had = new Map(before.map((line) => [basketLineKey(line.productId, line.variantId), line.quantity]));
+    return after.flatMap((line) => {
+        const grew = line.quantity - (had.get(basketLineKey(line.productId, line.variantId)) ?? 0);
+        return grew > 0 ? [{ ...line, quantity: grew }] : [];
+    });
+}

package/dist/index.d.ts

@@ -22,7 +22,7 @@ export { servedLanguage } from "./locales.js";
 export { alternateLinks, localeRouting, localizeHref, resolveLocalePath } from "./locale-routing.js";
 export type { LocalePath, LocaleRouting } from "./locale-routing.js";
 export type { StorefrontPageMatch, StorefrontPageType, StorefrontPathParams, StorefrontRoute } from "./routes.js";
-export { createBasketStore, createMemoryStorageAdapter, createLocalStorageAdapter, DEFAULT_BASKET_STORAGE_KEY, toOrderItems, } from "./basket.js";
+export { addedLines, createBasketStore, createMemoryStorageAdapter, createLocalStorageAdapter, DEFAULT_BASKET_STORAGE_KEY, toOrderItems, } from "./basket.js";
 export { MAX_BASKET_LINES, MAX_BASKET_LINE_QUANTITY, basketLineKey } from "./basket-line.js";
 export type { BasketStore, BasketStorageAdapter, BasketStoreOptions, BasketListener, BasketSelectionLine, } from "./basket.js";
 export { createOtpMachine, createOtpTransport, mapOtpResponse, otpTransportFailure, } from "./otp.js";
@@ -35,8 +35,8 @@ export { createQuoter } from "./quote.js";
 export type { Quoter, QuoterOptions, QuoteResult } from "./quote.js";
 export { isOrderNumber, ORDER_NUMBER_PATTERN } from "./order-number.js";
 export { DEFAULT_COLLECTION_HANDLES, PRODUCT_SORTS, SHOPPER_ORDER_JOURNEY, SHOPPER_ORDER_STAGES } from "./catalog.js";
-export { SEO_TEXT_LIMITS, jsonLd, productMeta, productStructuredData } from "./seo.js";
-export type { PageMeta, ProductStructuredDataOptions } from "./seo.js";
+export { SEO_TEXT_LIMITS, canonicalUrl, jsonLd, productMeta, productStructuredData } from "./seo.js";
+export type { CanonicalPage, PageMeta, ProductStructuredDataOptions } from "./seo.js";
 export { REVIEW_REFUSAL_CODES, REVIEW_TEXT_LIMITS } from "./reviews.js";
 export type { ReviewRefusalCode } from "./reviews.js";
 export type { CommuneTuple } from "./data/communes.js";

package/dist/index.js

@@ -16,7 +16,7 @@ export { MAX_RESOLVED_PREFILL_LENGTH, PREFILL_TOKENS, stripTrackingParams, trunc
 export { STOREFRONT_PAGE_PATHS, STOREFRONT_ROUTES, matchStorefrontPath, showsWidgetOn, storefrontPath } from "./routes.js";
 export { servedLanguage } from "./locales.js";
 export { alternateLinks, localeRouting, localizeHref, resolveLocalePath } from "./locale-routing.js";
-export { createBasketStore, createMemoryStorageAdapter, createLocalStorageAdapter, DEFAULT_BASKET_STORAGE_KEY, toOrderItems, } from "./basket.js";
+export { addedLines, createBasketStore, createMemoryStorageAdapter, createLocalStorageAdapter, DEFAULT_BASKET_STORAGE_KEY, toOrderItems, } from "./basket.js";
 export { MAX_BASKET_LINES, MAX_BASKET_LINE_QUANTITY, basketLineKey } from "./basket-line.js";
 export { createOtpMachine, createOtpTransport, mapOtpResponse, otpTransportFailure, } from "./otp.js";
 export { WILAYAS } from "./data/wilayas.js";
@@ -26,7 +26,7 @@ export { readCartQuote, readCouponOutcome, readShippingRates } from "./answer-re
 export { createQuoter } from "./quote.js";
 export { isOrderNumber, ORDER_NUMBER_PATTERN } from "./order-number.js";
 export { DEFAULT_COLLECTION_HANDLES, PRODUCT_SORTS, SHOPPER_ORDER_JOURNEY, SHOPPER_ORDER_STAGES } from "./catalog.js";
-export { SEO_TEXT_LIMITS, jsonLd, productMeta, productStructuredData } from "./seo.js";
+export { SEO_TEXT_LIMITS, canonicalUrl, jsonLd, productMeta, productStructuredData } from "./seo.js";
 export { REVIEW_REFUSAL_CODES, REVIEW_TEXT_LIMITS } from "./reviews.js";
 export { normalizeAlgerianPhone, toLocalAlgerianMobile } from "./phone.js";
 export * from "./types.js";

package/dist/seo.d.ts

@@ -1,3 +1,9 @@
+/**
+ * What a product page tells search engines and shared links: its title and
+ * description, and its structured data — decided once, so every theme ranks
+ * the same products the same way.
+ */
+import { type LocaleRouting } from "./locale-routing.js";
 import type { Product, ProductList } from "./types.js";
 /** The lengths a search-engine title and description may have: about what a search result shows. */
 export declare const SEO_TEXT_LIMITS: {
@@ -44,4 +50,19 @@ export declare function productStructuredData(product: Product, options: Product
  * ```
  */
 export declare function jsonLd(value: unknown): string;
+/** Where a page is, as its canonical address needs it: the route it renders, in its language. */
+export interface CanonicalPage {
+    /** The page's path without its language prefix (`/products/robe`). */
+    pathname: string;
+    locale: string;
+    routing: LocaleRouting;
+}
+/**
+ * A page's canonical address: its path in its language on `origin`, keeping
+ * only the listing page it shows (`?page=2`). An order (`?sort=`), a search,
+ * an ad's click id (`fbclid`, `utm_*`) or a coupon in the address is the same
+ * page to a search engine, and a canonical that kept them would split one
+ * page into many.
+ */
+export declare function canonicalUrl(origin: string, page: CanonicalPage, search?: string | URLSearchParams): string;
 export {};

package/dist/seo.js

@@ -3,6 +3,7 @@
  * description, and its structured data — decided once, so every theme ranks
  * the same products the same way.
  */
+import { localizeHref } from "./locale-routing.js";
 import { getProductView } from "./product-view.js";
 import { initialVariant } from "./variant-picker.js";
 /** The lengths a search-engine title and description may have: about what a search result shows. */
@@ -27,7 +28,8 @@ export function productMeta(product) {
     const written = collapse(product.metaDescription ?? "");
     if (written)
         return { title, description: written };
-    const plain = product.descriptionPlain ?? (product.descriptionFormat === "text" ? product.description : null);
+    // An empty plain text is no plain text: a text row is then read as it is.
+    const plain = product.descriptionPlain || (product.descriptionFormat === "text" ? product.description : null);
     const text = collapse(plain ?? "");
     return { title, description: text ? shorten(text, SEO_TEXT_LIMITS.descriptionMax) : null };
 }
@@ -85,3 +87,17 @@ export function jsonLd(value) {
         .replace(/\u2028/g, "\\u2028")
         .replace(/\u2029/g, "\\u2029");
 }
+/**
+ * A page's canonical address: its path in its language on `origin`, keeping
+ * only the listing page it shows (`?page=2`). An order (`?sort=`), a search,
+ * an ad's click id (`fbclid`, `utm_*`) or a coupon in the address is the same
+ * page to a search engine, and a canonical that kept them would split one
+ * page into many.
+ */
+export function canonicalUrl(origin, page, search = "") {
+    const url = new URL(localizeHref(page.pathname, page.locale, page.routing), origin);
+    const asked = Number(new URLSearchParams(search).get("page"));
+    if (Number.isSafeInteger(asked) && asked > 1)
+        url.searchParams.set("page", String(asked));
+    return url.href;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wocart/storefront",
-  "version": "1.21.0",
+  "version": "1.22.0",
   "description": "Typed, validated SDK for Wocart cash-on-delivery storefronts: catalog reads, basket, checkout, OTP and order tracking, with Astro adapters.",
   "keywords": [
     "wocart",