@wocart/storefront 2.1.0 → 2.2.0

package/CHANGELOG.md

@@ -5,6 +5,24 @@ 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.
 
+## 2.2.0 — 2026-11-01
+
+### Added
+
+- `localWhatsAppWidget(config)`: the WhatsApp widget as a page in
+  `config.locale` shows it. Its texts are written once, in the store's
+  primary language; on a page in another language they are null, so a theme
+  shows its own words in the shopper's language instead of the merchant's in
+  another one. The agent's name and every setting stay.
+
+### Fixed
+
+- `formatMoney` writes the currency symbol after the amount in every
+  language, as Algerian prices are written (`5 000 DA`, `5,000 DA`,
+  `5.000 دج`), joined by a no-break space so the two never wrap apart. French
+  and English put it before the amount (`DA 5 000`). Without a symbol it is
+  the amount alone, with no stray space.
+
 ## 2.1.0 — 2026-10-31
 
 ### Added

package/USAGE.md

@@ -223,7 +223,7 @@ server directly.
 | `isWilayaId` | Whether a value is a wilaya id — the range `WilayaIdSchema` checks on the server, without a schema in the browser |
 | `readShippingRates`, `readCouponOutcome` | Read in the browser what the server handed it — the rates a page carries, a quote's coupon outcome — accepting exactly what `ShippingRatesSchema` / `CouponOutcomeSchema` accept, without Zod |
 | `normalizeAlgerianPhone`, `toLocalAlgerianMobile` | The one Algerian phone rule (accept/format) |
-| `resolvePrefillText`, `buildWhatsAppHref`, `stripTrackingParams`, `truncateAtWordBoundary`, `PREFILL_TOKENS`, `MAX_RESOLVED_PREFILL_LENGTH` | WhatsApp prefill text and the `wa.me` link |
+| `localWhatsAppWidget`, `resolvePrefillText`, `buildWhatsAppHref`, `stripTrackingParams`, `truncateAtWordBoundary`, `PREFILL_TOKENS`, `MAX_RESOLVED_PREFILL_LENGTH` | the widget in the page's language, WhatsApp prefill text and the `wa.me` link |
 | `storefrontPath`, `matchStorefrontPath`, `STOREFRONT_PAGE_PATHS` | The page types and their public paths: build a link, recognise a page |
 | `showsWidgetOn`, `STOREFRONT_ROUTES` | Which widget surface a pathname is (`STOREFRONT_ROUTES` deprecated) |
 | `productImageSource` | Which photo represents a product (cover → gallery fallback) |
@@ -1926,21 +1926,30 @@ already written, and the thank-you page offers the same handoff for an order.
 The template belongs to the merchant — the dashboard authors and previews it
 within the platform's limits — while the page resolves it:
 
+The merchant writes the widget's texts once, in the store's primary language.
+Read the widget with `localWhatsAppWidget(config)`: on a page in another
+language its texts (labels, welcome, prefills) are null, so the theme shows its
+own words in the shopper's language; the agent's name and the settings stay.
+
 ~~~ts
 import {
   buildWhatsAppHref,
+  localWhatsAppWidget,
   resolvePrefillText,
 } from "@wocart/storefront";
 
+const widget = localWhatsAppWidget(config);
+if (!widget) return;
+
 const text = resolvePrefillText({
-  template: config.whatsapp.prefillProduct ?? "Hello {store}, about {product}: {url}",
+  template: widget.prefillProduct ?? "Hello {store}, about {product}: {url}",
   storeName: config.name,
   productName: product.name, // falls back to the store name when absent
   url: Astro.url.href,       // ad-click parameters (`utm_*`, `fbclid`) stripped
   orderNumber: null,         // resolves to nothing when absent
 });
 
-const href = buildWhatsAppHref(config.whatsapp.href, text);
+const href = buildWhatsAppHref(widget.href, text);
 ~~~
 
 Three rules come with it, and a theme must not re-implement them:

package/dist/index.d.ts

@@ -15,7 +15,7 @@ export { isMediaKey, mediaImageSrcset, mediaImageUrl, mediaUrl, pictureOf } from
 export type { MediaDelivery, MediaDeliveryKind, MediaImage, MediaImageParams, MediaImageSrcsetOptions, PickedImage, Picture } from "./utils/image.js";
 export { productImageSource } from "./utils/product-image.js";
 export type { ProductImageSourceInput } from "./utils/product-image.js";
-export { MAX_RESOLVED_PREFILL_LENGTH, PREFILL_TOKENS, stripTrackingParams, truncateAtWordBoundary, resolvePrefillText, buildWhatsAppHref, } from "./whatsapp.js";
+export { MAX_RESOLVED_PREFILL_LENGTH, PREFILL_TOKENS, stripTrackingParams, truncateAtWordBoundary, resolvePrefillText, buildWhatsAppHref, localWhatsAppWidget, } from "./whatsapp.js";
 export type { PrefillToken, ResolvePrefillParams } from "./whatsapp.js";
 export { STOREFRONT_PAGE_PATHS, STOREFRONT_ROUTES, matchStorefrontPath, showsWidgetOn, storefrontPath } from "./routes.js";
 export { servedLanguage } from "./locales.js";

package/dist/index.js

@@ -12,7 +12,7 @@
 export { formatMoney } from "./utils/money.js";
 export { isMediaKey, mediaImageSrcset, mediaImageUrl, mediaUrl, pictureOf } from "./utils/image.js";
 export { productImageSource } from "./utils/product-image.js";
-export { MAX_RESOLVED_PREFILL_LENGTH, PREFILL_TOKENS, stripTrackingParams, truncateAtWordBoundary, resolvePrefillText, buildWhatsAppHref, } from "./whatsapp.js";
+export { MAX_RESOLVED_PREFILL_LENGTH, PREFILL_TOKENS, stripTrackingParams, truncateAtWordBoundary, resolvePrefillText, buildWhatsAppHref, localWhatsAppWidget, } from "./whatsapp.js";
 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";

package/dist/utils/money.d.ts

@@ -2,7 +2,7 @@
  * Deep Money Formatter
  *
  * One formatter for every price a storefront shows.
- * Handles locale-aware formatting, RTL symbol positioning, and Arabic-Indic digits.
+ * Handles locale-aware formatting and Arabic-Indic digits; the symbol follows the amount.
  *
  * Design principle: ONE function that handles all cases. Callers curry if needed.
  */
@@ -26,14 +26,14 @@ export interface MoneyFormatOptions {
  * // Arabic: 5,000 دج (with Arabic-Indic digits)
  * formatMoney(5000, { symbol: 'دج', locale: 'ar-DZ' })
  *
- * // French: DA 5 000,00
- * formatMoney(5000, { symbol: 'DA', locale: 'fr-FR' })
+ * // French: 5 000,00 DA
+ * formatMoney(5000, { symbol: 'DA', locale: 'fr-FR', decimals: 2 })
  *
- * // English: DA 5,000.00
+ * // English: 5,000 DA
  * formatMoney(5000, { symbol: 'DA', locale: 'en-US' })
- *
- * // No decimals: 5,000 دج
- * formatMoney(5000, { symbol: 'دج', locale: 'ar-DZ', decimals: 0 })
  * ```
+ *
+ * The symbol follows the amount in every language, as Algerian prices are
+ * written, joined by a no-break space so the two never wrap apart.
  */
 export declare function formatMoney(amount: number, options: MoneyFormatOptions): string;

package/dist/utils/money.js

@@ -2,7 +2,7 @@
  * Deep Money Formatter
  *
  * One formatter for every price a storefront shows.
- * Handles locale-aware formatting, RTL symbol positioning, and Arabic-Indic digits.
+ * Handles locale-aware formatting and Arabic-Indic digits; the symbol follows the amount.
  *
  * Design principle: ONE function that handles all cases. Callers curry if needed.
  */
@@ -18,15 +18,15 @@
  * // Arabic: 5,000 دج (with Arabic-Indic digits)
  * formatMoney(5000, { symbol: 'دج', locale: 'ar-DZ' })
  *
- * // French: DA 5 000,00
- * formatMoney(5000, { symbol: 'DA', locale: 'fr-FR' })
+ * // French: 5 000,00 DA
+ * formatMoney(5000, { symbol: 'DA', locale: 'fr-FR', decimals: 2 })
  *
- * // English: DA 5,000.00
+ * // English: 5,000 DA
  * formatMoney(5000, { symbol: 'DA', locale: 'en-US' })
- *
- * // No decimals: 5,000 دج
- * formatMoney(5000, { symbol: 'دج', locale: 'ar-DZ', decimals: 0 })
  * ```
+ *
+ * The symbol follows the amount in every language, as Algerian prices are
+ * written, joined by a no-break space so the two never wrap apart.
  */
 export function formatMoney(amount, options) {
     const { symbol, locale, decimals = 0 } = options;
@@ -35,9 +35,5 @@ export function formatMoney(amount, options) {
         minimumFractionDigits: decimals,
         maximumFractionDigits: decimals,
     });
-    // RTL-aware symbol positioning
-    // Arabic: suffix (5,000.00 دج)
-    // French/English: prefix (DA 5,000.00)
-    const isRTL = locale.startsWith("ar");
-    return isRTL ? `${formatted} ${symbol}` : `${symbol} ${formatted}`;
+    return symbol ? `${formatted}\u00A0${symbol}` : formatted;
 }

package/dist/whatsapp.d.ts

@@ -16,6 +16,7 @@
  * 3. **The encoded text is appended the same way everywhere**, so a base href
  *    that already carries a query string keeps it.
  */
+import type { StoreConfig, StoreWhatsAppWidget } from "./types.js";
 /**
  * The hard cap on a resolved prefill message, in characters.
  *
@@ -53,3 +54,10 @@ export interface ResolvePrefillParams {
 export declare function resolvePrefillText({ template, storeName, productName, url, orderNumber, }: ResolvePrefillParams): string;
 /** Appends the resolved message to a `wa.me` href, encoded and query-safe. */
 export declare function buildWhatsAppHref(baseHref: string, text: string): string;
+/**
+ * The WhatsApp widget as a page in `config.locale` shows it. The merchant
+ * writes its texts once, in the store's primary language (`config.lang`), so
+ * a page in another language gets them as null and shows the theme's own
+ * words in its language instead; the agent's name and every setting stay.
+ */
+export declare function localWhatsAppWidget(config: Pick<StoreConfig, "whatsapp" | "lang" | "locale">): StoreWhatsAppWidget | null;

package/dist/whatsapp.js

@@ -1,21 +1,3 @@
-/**
- * WhatsApp prefill messages — the storefront's message rule.
- *
- * A storefront's WhatsApp launcher hands the shopper to WhatsApp with the
- * message already written. The template belongs to the merchant (the dashboard
- * authors it within the limits below), and the page
- * resolves it: `{store}`, `{product}`, `{url}`, `{order}`.
- *
- * Three rules live here so no theme re-invents them:
- *
- * 1. **Ad-click parameters are stripped from `{url}`.** A shopper arriving from
- *    a paid ad should not hand the merchant's WhatsApp a `fbclid`-laden link.
- * 2. **The resolved message is capped at `MAX_RESOLVED_PREFILL_LENGTH`, cut at
- *    a word boundary.** Browsers and WhatsApp both truncate silently past a
- *    point; a cut mid-word reads as a broken store.
- * 3. **The encoded text is appended the same way everywhere**, so a base href
- *    that already carries a query string keeps it.
- */
 /**
  * The hard cap on a resolved prefill message, in characters.
  *
@@ -87,3 +69,17 @@ export function buildWhatsAppHref(baseHref, text) {
     const separator = baseHref.includes("?") ? "&" : "?";
     return `${baseHref}${separator}text=${encodeURIComponent(text)}`;
 }
+/** The widget's texts the merchant writes once, in the store's primary language. */
+const WIDGET_TEXTS = ["caption", "welcomeMessage", "launcherLabel", "ctaLabel", "prefillGeneral", "prefillProduct", "thankYouButtonLabel", "prefillThankYou"];
+/**
+ * The WhatsApp widget as a page in `config.locale` shows it. The merchant
+ * writes its texts once, in the store's primary language (`config.lang`), so
+ * a page in another language gets them as null and shows the theme's own
+ * words in its language instead; the agent's name and every setting stay.
+ */
+export function localWhatsAppWidget(config) {
+    const widget = config.whatsapp;
+    if (!widget || config.locale === config.lang)
+        return widget;
+    return { ...widget, ...Object.fromEntries(WIDGET_TEXTS.map((key) => [key, null])) };
+}

package/package.json

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