@velastack/cms 0.8.0 → 0.9.0

package/README.md

@@ -502,6 +502,41 @@ A cart whose checkout is a WhatsApp chat. Visitors add items with `whatsappCart.
 
 - **One currency, the business's own.** Every price is in it, and the order and message are too. It comes from the `currency` Site Option (a `currency` field in any group of `createCms({ site })`), or the `currency` prop. `formatPrice` formats an amount in the page's language in the business's country (`siteLocale`), so on a Mexican site an English page shows MXN as `MX$5.50` and a Spanish one as `$5.50`.
 - **The number** is the field's own setting, or the `number` prop when the template already keeps it in its contact details (`<CmsContact>`'s `whatsapp`), so an editor enters it once.
+- **Another currency on the page** (see [`displayCurrency`](#displaycurrency-prices-in-the-visitors-currency)): `formatPrice` converts and marks the estimate `≈`, and the message gets an `{estimate}` placeholder with the total as the visitor read it. The order and the record stay in the business's currency.
+
+### `displayCurrency`: prices in the visitor's currency
+
+A site's prices are in the business's currency. When the `currencies` Site Option lists more (a hotel: `USD, EUR`), a visitor can read prices in one of them: converted at the day's rate and marked `≈`, an estimate of a price that is still charged in the business's currency. The store is headless; the template draws the select.
+
+```svelte
+<script lang="ts">
+	import { onMount } from 'svelte';
+	import { displayCurrency, CmsCollection } from '@velastack/cms';
+	onMount(() => displayCurrency.load());
+</script>
+
+{#if displayCurrency.offered.length > 1}
+	<select
+		value={displayCurrency.current}
+		onchange={(e) => displayCurrency.set(e.currentTarget.value)}
+	>
+		{#each displayCurrency.offered as code (code)}<option value={code}>{code}</option>{/each}
+	</select>
+{/if}
+
+<CmsCollection name="rooms" scope="root">
+	{#snippet children(rooms)}
+		{#each rooms as room (room.id)}
+			<p>{displayCurrency.formatCollectionPrice(room.price, cms.locale)}</p>
+		{/each}
+	{/snippet}
+</CmsCollection>
+```
+
+- `offered` is the business's currency first, then the others; `current` is the visitor's pick, kept in a `currency` cookie for a year; `set(code)` changes it.
+- `format(amount, from?, language?)` and `formatCollectionPrice(price, language?)` return the price as the visitor reads it, formatted for the page's language in the business's country (`siteLocale`), with `≈` when converted. `convert(amount, from?)` gives the number, or `null` without a rate.
+- The rates are central bank reference rates blended by [Frankfurter](https://frankfurter.dev), published once a day at `velastack.dev/v1/rates` for every site; `load()` fetches them in the browser once a day and keeps them in localStorage. A page without rates shows the business's currency. Nothing is fetched while the site offers one currency.
+- On a static site the first render is in the business's currency and the visitor's pick applies after load, since there is no server to read the cookie.
 - **Prices are optional**, and written as an editor types them (`4.5`). `cart.subtotal` exists only when every item has a price; otherwise the business quotes the total in the chat.
 - **The message is the editor's**, set from the pencil like `CmsWhatsAppForm`'s, with `{ref}`, `{items}`, `{total}`, `{name}`, `{phone}` and `{note}`. Until one is set, a default lists the items, the total and the customer. Lines an empty placeholder leaves blank are dropped.
 - **After checkout**, `placed` holds the order's reference and chat link until `cart.clear()`. Adding an item starts the next order.
@@ -656,7 +691,7 @@ editable page metadata (cms.metadata)
 
 ### Site options
 
-`createCms({ site })` declares the **Site Options** panel: project-wide values that never render on the page — the schema.org type (`enum`), the default share image (`image`), which locales are enabled (`boolean`), the business's currency and country (`text`, ISO 4217 and ISO 3166-1 alpha-2, in a group such as `business`: `siteCurrency`, `siteCountry` and `siteLocale` find a `currency` or `country` field in any group). Field types are `text`, `markdown`, `number`, `datetime`, `url`, `color`, `image`, `enum` (with `values`) and `boolean`. Anything a visitor sees belongs in the root layout scope, edited in place with `scope="root"`; the site tree is one non-localised tree per project.
+`createCms({ site })` declares the **Site Options** panel: project-wide values that never render on the page — the schema.org type (`enum`), the default share image (`image`), which locales are enabled (`boolean`), the business's currency and country (`text`, ISO 4217 and ISO 3166-1 alpha-2, in a group such as `business`: `siteCurrency`, `siteCountry` and `siteLocale` find a `currency` or `country` field in any group), and the other currencies it shows prices in (`currencies`, a comma-separated `text`; `siteCurrencies`). Field types are `text`, `markdown`, `number`, `datetime`, `url`, `color`, `image`, `enum` (with `values`) and `boolean`. Anything a visitor sees belongs in the root layout scope, edited in place with `scope="root"`; the site tree is one non-localised tree per project.
 
 ## Adapters
 

package/dist/components/cms/cms-whatsapp-cart.svelte

@@ -33,7 +33,6 @@
 	import type { HTMLFormAttributes } from 'svelte/elements';
 	import {
 		fillMessage,
-		formatMoney,
 		openChat,
 		orderPlaceholders,
 		orderRef,
@@ -45,6 +44,7 @@
 	import Structured from './cms-structured.svelte';
 	import FormControls from './cms-form-controls.svelte';
 	import { cms, cmsStore } from './cms-store.svelte.js';
+	import { displayCurrency } from './display-currency.svelte.js';
 	import { siteCurrency, siteLocale } from '../../core/site-currency.js';
 	import { useFormTarget, type FormStatus } from './use-form-target.svelte.js';
 	import { setWhatsAppFieldNames } from './cms-whatsapp-form.svelte';
@@ -121,12 +121,26 @@
 		get placed() {
 			return whatsappCart.placed;
 		},
-		formatPrice: (amount) => formatMoney(amount, whatsappCart.currency, pageLocale())
+		// In the currency the visitor reads prices in, as an estimate when it is
+		// not the business's own.
+		formatPrice: (amount) => displayCurrency.format(amount, whatsappCart.currency, pageLocale())
 	};
 
 	// The cart lives in the browser, so the server renders it empty and it
 	// fills in here.
-	onMount(() => whatsappCart.load());
+	onMount(() => {
+		whatsappCart.load();
+		displayCurrency.load();
+	});
+
+	/** `≈ US$20`, when the visitor was reading prices in another currency; else blank. */
+	const estimateOf = (order: Order): string => {
+		if (order.subtotal === undefined || displayCurrency.current === order.currency) return '';
+		const converted = displayCurrency.convert(order.subtotal, order.currency);
+		return converted === null
+			? ''
+			: displayCurrency.format(order.subtotal, order.currency, pageLocale());
+	};
 
 	const field = (body: FormData, name: string) => {
 		const value = body.get(name);
@@ -179,7 +193,10 @@
 			subtotal: orderSubtotal(lines, whatsappCart.currency)
 		};
 		const text = tidyMessage(
-			fillMessage(settings.message || DEFAULT_ORDER_MESSAGE, orderPlaceholders(order, pageLocale()))
+			fillMessage(settings.message || DEFAULT_ORDER_MESSAGE, {
+				...orderPlaceholders(order, pageLocale()),
+				estimate: estimateOf(order)
+			})
 		);
 		const href = whatsappHref(number || settings.number, text);
 		if (!href) {

package/dist/components/cms/display-currency.svelte.d.ts

@@ -0,0 +1,42 @@
+import type { CollectionPrice } from '../../core/shapes/collection.js';
+export declare const RATES_URL = "https://velastack.dev/v1/rates";
+export type Rates = {
+    base: string;
+    date: string;
+    rates: Record<string, number>;
+    fetchedAt: number;
+};
+declare class DisplayCurrency {
+    #private;
+    rates: Rates | null;
+    /** The business's currency, from Site Options. */
+    get home(): string;
+    /** The currencies the site shows prices in: the business's own, then the others it offers. */
+    get offered(): string[];
+    /** The currency prices show in now. */
+    get current(): string;
+    /** Reads the cookie and the day's rates, once, in the browser. */
+    load(): void;
+    /** Shows prices in `code`, one of `offered`, and remembers it. */
+    set(code: string): void;
+    /** `amount` in `from` as the current currency, or `null` without a rate for either. */
+    convert(amount: number, from?: string): number | null;
+    /**
+     * `amount` in `from`, as the visitor should read it: in the current currency
+     * with `≈` when it was converted, else as it is. `language` is the page's
+     * (`cms.locale`, or `<html lang>`), formatted for the business's country.
+     */
+    format(amount: number, from?: string, language?: string): string;
+    /**
+     * A collection item's price (`from €120 / night`) as the visitor reads it:
+     * converted and marked `≈` when they picked another currency. Empty
+     * without an amount, as `formatCollectionPrice` is.
+     */
+    formatCollectionPrice(price: CollectionPrice, language?: string): string;
+    /** For tests and servers that already have the day's rates. */
+    useRates(rates: Rates | null): void;
+}
+/** `amount` in `code`, formatted for `locale`; a code Intl refuses prints as `CODE 12`. */
+export declare const money: (amount: number, code: string, locale: string) => string;
+export declare const displayCurrency: DisplayCurrency;
+export {};

package/dist/components/cms/display-currency.svelte.js

@@ -0,0 +1,143 @@
+/**
+ * The currency a visitor reads prices in.
+ *
+ * Every price on a site is in the business's currency, the `currency` Site
+ * Option. When the `currencies` option offers more, the visitor can pick one
+ * and sees each price converted at the day's rate, marked `≈`: an estimate,
+ * never what they are charged. The choice is kept in a cookie for a year.
+ *
+ * Rates come from velastack.dev, which publishes central bank reference rates
+ * once for every site (https://velastack.dev/v1/rates); they are fetched in
+ * the browser once a day and kept in localStorage. Headless: a template draws
+ * its own select from `offered` and `current`, and calls `set`.
+ */
+import { cms } from './cms-store.svelte.js';
+import { siteCurrencies, siteCurrency, siteLocale } from '../../core/site-currency.js';
+export const RATES_URL = 'https://velastack.dev/v1/rates';
+const COOKIE = 'currency';
+const RATES_KEY = 'vela-cms:rates';
+const DAY = 24 * 60 * 60 * 1000;
+class DisplayCurrency {
+    /** The visitor's pick, or `''` for the business's own currency. */
+    #picked = $state('');
+    rates = $state(null);
+    #loaded = false;
+    /** The business's currency, from Site Options. */
+    get home() {
+        return siteCurrency(cms.site) ?? '';
+    }
+    /** The currencies the site shows prices in: the business's own, then the others it offers. */
+    get offered() {
+        const home = this.home;
+        if (!home)
+            return [];
+        return [home, ...siteCurrencies(cms.site).filter((code) => code !== home)];
+    }
+    /** The currency prices show in now. */
+    get current() {
+        return this.#picked && this.offered.includes(this.#picked) ? this.#picked : this.home;
+    }
+    /** Reads the cookie and the day's rates, once, in the browser. */
+    load() {
+        if (typeof document === 'undefined' || this.#loaded)
+            return;
+        this.#loaded = true;
+        const saved = document.cookie.match(/(?:^|;\s*)currency=([A-Z]{3})/)?.[1];
+        if (saved)
+            this.#picked = saved;
+        if (this.current !== this.home)
+            void this.#loadRates();
+    }
+    /** Shows prices in `code`, one of `offered`, and remembers it. */
+    set(code) {
+        if (!this.offered.includes(code))
+            return;
+        this.#picked = code;
+        if (typeof document !== 'undefined') {
+            document.cookie = `${COOKIE}=${code}; path=/; max-age=${365 * 24 * 60 * 60}; samesite=lax`;
+        }
+        if (code !== this.home)
+            void this.#loadRates();
+    }
+    /** `amount` in `from` as the current currency, or `null` without a rate for either. */
+    convert(amount, from = this.home) {
+        if (from === this.current)
+            return amount;
+        const rates = this.rates?.rates;
+        const fromRate = rates?.[from];
+        const toRate = rates?.[this.current];
+        if (!fromRate || !toRate)
+            return null;
+        return (amount / fromRate) * toRate;
+    }
+    /**
+     * `amount` in `from`, as the visitor should read it: in the current currency
+     * with `≈` when it was converted, else as it is. `language` is the page's
+     * (`cms.locale`, or `<html lang>`), formatted for the business's country.
+     */
+    format(amount, from = this.home, language) {
+        const locale = siteLocale(cms.site, language ?? pageLanguage()) ?? 'en';
+        const converted = this.convert(amount, from);
+        if (converted === null || from === this.current)
+            return money(amount, from, locale);
+        return `≈ ${money(converted, this.current, locale)}`;
+    }
+    /**
+     * A collection item's price (`from €120 / night`) as the visitor reads it:
+     * converted and marked `≈` when they picked another currency. Empty
+     * without an amount, as `formatCollectionPrice` is.
+     */
+    formatCollectionPrice(price, language) {
+        if (price.amount === null)
+            return '';
+        const amount = this.format(price.amount, price.currency || this.home, language);
+        return [price.prefix, amount, price.period ? `/ ${price.period}` : '']
+            .filter(Boolean)
+            .join(' ');
+    }
+    /** For tests and servers that already have the day's rates. */
+    useRates(rates) {
+        this.rates = rates;
+    }
+    async #loadRates() {
+        if (this.rates && Date.now() - this.rates.fetchedAt < DAY)
+            return;
+        try {
+            const cached = JSON.parse(localStorage.getItem(RATES_KEY) ?? 'null');
+            if (cached && Date.now() - cached.fetchedAt < DAY) {
+                this.rates = cached;
+                return;
+            }
+        }
+        catch {
+            // Unreadable storage: fetch instead.
+        }
+        try {
+            const response = await fetch(RATES_URL);
+            if (!response.ok)
+                return;
+            const body = (await response.json());
+            const rates = { ...body, fetchedAt: Date.now() };
+            this.rates = rates;
+            localStorage.setItem(RATES_KEY, JSON.stringify(rates));
+        }
+        catch {
+            // No rates: prices stay in the business's currency.
+        }
+    }
+}
+const pageLanguage = () => (typeof document !== 'undefined' && document.documentElement.lang) || undefined;
+/** `amount` in `code`, formatted for `locale`; a code Intl refuses prints as `CODE 12`. */
+export const money = (amount, code, locale) => {
+    try {
+        return new Intl.NumberFormat(locale, {
+            style: 'currency',
+            currency: code,
+            maximumFractionDigits: Number.isInteger(amount) && amount >= 100 ? 0 : 2
+        }).format(amount);
+    }
+    catch {
+        return `${code} ${amount}`.trim();
+    }
+};
+export const displayCurrency = new DisplayCurrency();

package/dist/core/forms/order-message.d.ts

@@ -4,7 +4,11 @@
  */
 /** The `{placeholders}` an order message can use. */
 export declare const ORDER_PLACEHOLDERS: string[];
-/** Until the editor writes one. Lines left empty (no total, no note) are dropped. */
-export declare const DEFAULT_ORDER_MESSAGE = "Hi! I'd like to place an order ({ref}):\n\n{items}\n\n{total}\n\n{name} \u00B7 {phone}\n{note}";
+/**
+ * Until the editor writes one. Lines left empty (no total, no estimate, no
+ * note) are dropped. `{estimate}` is the total in the currency the visitor
+ * was reading prices in, when it was not the business's own.
+ */
+export declare const DEFAULT_ORDER_MESSAGE = "Hi! I'd like to place an order ({ref}):\n\n{items}\n\n{total}\n{estimate}\n\n{name} \u00B7 {phone}\n{note}";
 /** Drops the blank lines and dangling spaces that empty placeholders leave behind. */
 export declare const tidyMessage: (message: string) => string;

package/dist/core/forms/order-message.js

@@ -3,9 +3,13 @@
  * the order by `@velastack/whatsapp`'s `orderPlaceholders`.
  */
 /** The `{placeholders}` an order message can use. */
-export const ORDER_PLACEHOLDERS = ['ref', 'items', 'total', 'name', 'phone', 'note'];
-/** Until the editor writes one. Lines left empty (no total, no note) are dropped. */
-export const DEFAULT_ORDER_MESSAGE = "Hi! I'd like to place an order ({ref}):\n\n{items}\n\n{total}\n\n{name} · {phone}\n{note}";
+export const ORDER_PLACEHOLDERS = ['ref', 'items', 'total', 'estimate', 'name', 'phone', 'note'];
+/**
+ * Until the editor writes one. Lines left empty (no total, no estimate, no
+ * note) are dropped. `{estimate}` is the total in the currency the visitor
+ * was reading prices in, when it was not the business's own.
+ */
+export const DEFAULT_ORDER_MESSAGE = "Hi! I'd like to place an order ({ref}):\n\n{items}\n\n{total}\n{estimate}\n\n{name} · {phone}\n{note}";
 /** Drops the blank lines and dangling spaces that empty placeholders leave behind. */
 export const tidyMessage = (message) => message
     .replace(/[ \t]+$/gm, '')

package/dist/core/site-currency.d.ts

@@ -14,6 +14,13 @@
  * when none is set or the value is not a three-letter code.
  */
 export declare const siteCurrency: (site: Record<string, unknown> | undefined) => string | undefined;
+/**
+ * The other currencies the site shows prices in, from a `currencies` field
+ * declared like `currency`: a list, or a comma-separated text as the Site
+ * Options panel stores it. Upper-cased three-letter codes, deduplicated;
+ * empty when none is set.
+ */
+export declare const siteCurrencies: (site: Record<string, unknown> | undefined) => string[];
 /**
  * The ISO 3166-1 alpha-2 code of the country the business is in, from a
  * `country` field declared like `currency`. `undefined` when none is set.

package/dist/core/site-currency.js

@@ -38,6 +38,33 @@ const siteCode = (site, key, shape) => {
  * when none is set or the value is not a three-letter code.
  */
 export const siteCurrency = (site) => siteCode(site, 'currency', CURRENCY);
+/**
+ * The other currencies the site shows prices in, from a `currencies` field
+ * declared like `currency`: a list, or a comma-separated text as the Site
+ * Options panel stores it. Upper-cased three-letter codes, deduplicated;
+ * empty when none is set.
+ */
+export const siteCurrencies = (site) => {
+    if (!site)
+        return [];
+    const raw = site.currencies ??
+        Object.values(site).find((group) => group && typeof group === 'object' && !Array.isArray(group) && 'currencies' in group);
+    const value = raw && typeof raw === 'object' && !Array.isArray(raw)
+        ? raw.currencies
+        : raw;
+    const entries = Array.isArray(value)
+        ? value
+        : typeof value === 'string'
+            ? value.split(/[,\s]+/)
+            : [];
+    const codes = [];
+    for (const entry of entries) {
+        const code = asCode(entry, CURRENCY);
+        if (code && !codes.includes(code))
+            codes.push(code);
+    }
+    return codes;
+};
 /**
  * The ISO 3166-1 alpha-2 code of the country the business is in, from a
  * `country` field declared like `currency`. `undefined` when none is set.

package/dist/index.d.ts

@@ -40,7 +40,8 @@ export { default as CmsWhatsAppCart } from './components/cms/cms-whatsapp-cart.s
 export type { CmsWhatsAppCartState } from './components/cms/cms-whatsapp-cart.svelte';
 export { whatsappCart } from './components/cms/whatsapp-cart.svelte.js';
 export type { WhatsAppCartItem, WhatsAppPlacedOrder } from './components/cms/whatsapp-cart.svelte.js';
-export { siteCountry, siteCurrency, siteLocale } from './core/site-currency.js';
+export { siteCountry, siteCurrencies, siteCurrency, siteLocale } from './core/site-currency.js';
+export { displayCurrency, money, type Rates } from './components/cms/display-currency.svelte.js';
 export * from './core/shapes/index.js';
 export { default as AdminBar } from './components/admin-bar/admin-bar.svelte';
 export { useCmsField, resolveScopeRef, ROOT_SCOPE_ID } from './components/cms/use-cms-field.svelte.js';

package/dist/index.js

@@ -41,7 +41,8 @@ export { default as CmsFormFields } from './components/cms/cms-form-fields.svelt
 export { default as CmsWhatsAppForm } from './components/cms/cms-whatsapp-form.svelte';
 export { default as CmsWhatsAppCart } from './components/cms/cms-whatsapp-cart.svelte';
 export { whatsappCart } from './components/cms/whatsapp-cart.svelte.js';
-export { siteCountry, siteCurrency, siteLocale } from './core/site-currency.js';
+export { siteCountry, siteCurrencies, siteCurrency, siteLocale } from './core/site-currency.js';
+export { displayCurrency, money } from './components/cms/display-currency.svelte.js';
 export * from './core/shapes/index.js';
 // Admin bar (sync wrapper; admin-bar-internal + seo-panel are async chunks)
 export { default as AdminBar } from './components/admin-bar/admin-bar.svelte';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@velastack/cms",
-	"version": "0.8.0",
+	"version": "0.9.0",
 	"description": "A scope-aware CMS for SvelteKit, for static or dynamic sites.",
 	"keywords": [
 		"svelte",