@uniweb/core 0.11.0 → 0.11.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/core",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "description": "Core classes for the Uniweb platform - Uniweb, Website, Page, Block",
   "type": "module",
   "exports": {
@@ -40,7 +40,7 @@
     "vitest": "^4.1.7"
   },
   "dependencies": {
-    "@uniweb/semantic-parser": "^1.2.3",
+    "@uniweb/semantic-parser": "^1.3.0",
     "@uniweb/theming": "^0.1.15"
   },
   "scripts": {

package/src/locale-config.js

@@ -41,6 +41,72 @@ function codeOf(entry) {
  * @param {*} value - The authored `languages` value.
  * @returns {boolean}
  */
+/**
+ * Human-readable display names for the locales a site is likely to declare.
+ *
+ * This lives in core, not kit, because core is what BUILDS the locale objects a
+ * foundation reads (`website.getLocales()`, `website.langs`). It used to live
+ * only in kit, so core could not resolve a label and left the field absent for
+ * a plain-string `languages:` entry — which meant the very form this module
+ * tells authors to migrate TO produced worse labels than the legacy object form
+ * it warns about. Measured 2026-08-23 on a site with 11 locales: dropping the
+ * `label:` keys silently turned "Français" into "fr" in the switcher, because
+ * the common foundation idiom is `locale.label || locale.code`.
+ *
+ * Kit re-exports this so `@uniweb/kit`'s `LOCALE_DISPLAY_NAMES` keeps working.
+ */
+export const LOCALE_DISPLAY_NAMES = {
+  en: 'English',
+  es: 'Español',
+  fr: 'Français',
+  de: 'Deutsch',
+  it: 'Italiano',
+  pt: 'Português',
+  nl: 'Nederlands',
+  pl: 'Polski',
+  ru: 'Русский',
+  ja: '日本語',
+  ko: '한국어',
+  zh: '中文',
+  'zh-CN': '简体中文',
+  'zh-TW': '繁體中文',
+  ar: 'العربية',
+  he: 'עברית',
+  hi: 'हिन्दी',
+  th: 'ไทย',
+  vi: 'Tiếng Việt',
+  tr: 'Türkçe',
+  uk: 'Українська',
+  cs: 'Čeština',
+  el: 'Ελληνικά',
+  hu: 'Magyar',
+  ro: 'Română',
+  sv: 'Svenska',
+  da: 'Dansk',
+  fi: 'Suomi',
+  no: 'Norsk',
+  id: 'Bahasa Indonesia',
+  ms: 'Bahasa Melayu'
+}
+
+/**
+ * Resolve a locale's display label.
+ *
+ * Priority: an explicitly configured `label` -> the display-name table -> the
+ * code uppercased. Accepts either a bare code string or a `{ code, label? }`
+ * object, so callers do not have to branch on which form the config used.
+ *
+ * @param {string|{code: string, label?: string}} entry
+ * @returns {string} Display label, or '' when the entry carries no code.
+ */
+export function localeLabel(entry) {
+  if (typeof entry === 'string') {
+    return LOCALE_DISPLAY_NAMES[entry] || entry.toUpperCase()
+  }
+  if (!entry || typeof entry.code !== 'string' || !entry.code) return ''
+  return entry.label || LOCALE_DISPLAY_NAMES[entry.code] || entry.code.toUpperCase()
+}
+
 export function isWildcardLanguages(value) {
   return value === '*' || (Array.isArray(value) && value.includes('*'))
 }

package/src/tracker.js

@@ -49,9 +49,10 @@
  * ## Field lifetime — captured once, replayed on every page view
  *
  * `document.referrer` and the landing `utm_*` params exist **at arrival and
- * nowhere afterwards**: the referrer never changes across SPA navigation, and
- * the params leave the URL on the first navigation. So they are captured once,
- * here, and attached to every `page_view` of the document.
+ * nowhere afterwards** — as does `continues`, which is derived from the same
+ * read: the referrer never changes across SPA navigation, and the params leave
+ * the URL on the first navigation. So they are captured once, here, and
+ * attached to every `page_view` of the document.
  *
  * ⇒ **Consequence worth knowing when reading the numbers:** a per-view facet
  * built on them is *derived, not observed*. `utm_source` counts "views by
@@ -113,11 +114,35 @@ function captureAcquisition() {
 
   // Same-origin referrers are dropped: internal navigation is not a referral,
   // and counting it would make a site its own top referrer on every page.
+  //
+  // ⭐ **But dropping it destroys the only thing separating two different
+  // events, so the fact that it WAS same-origin is kept as one bit.** A full
+  // document load happens either because someone arrived from outside, or
+  // because a visitor already on the site triggered a real navigation — a
+  // locale switch through kit's `<Link reload>` being the shipped case. Both
+  // reach a collector with no referrer: the first never had one, the second had
+  // it discarded here. ⇒ An "entry pages" metric built on that **invents**
+  // arrivals, counting a locale switch as somebody landing on the Spanish page.
+  //
+  // ⚖️ `continues` states the FACT, not the conclusion. Whether a continuation
+  // disqualifies an entry is the consumer's call; a field named for one metric
+  // ages badly the moment a second one wants it.
+  //
+  // ⛔ **It carries no identity and links nothing.** It says only *this document
+  // continues a visit*, never *which* — so the categorical claim in this file's
+  // header, that nothing persistent is minted, is untouched. Correlating two
+  // visits would be a session, which is exactly what is refused.
   const referrer = document.referrer
   if (referrer) {
     try {
       if (new URL(referrer).origin !== window.location.origin) {
         context.referrer = referrer
+      } else {
+        // Emitted only when true. Absent means "not a continuation" AND "an
+        // older runtime that never sent it" — indistinguishable on purpose,
+        // because that collapses to today's behaviour rather than to a wrong
+        // answer, and it keeps the common payload the size it already was.
+        context.continues = true
       }
     } catch {
       // Unparseable — treat as absent rather than forwarding a malformed value.

package/src/website.js

@@ -10,7 +10,7 @@ import EntityStore from './entity-store.js'
 import FetcherDispatcher from './fetcher-dispatcher.js'
 import ObservableState from './observable-state.js'
 import { normalizeSeo } from './seo.js'
-import { resolveDefaultLocale } from './locale-config.js'
+import { resolveDefaultLocale, localeLabel } from './locale-config.js'
 import { matchDynamicRoute, decodeRouteValue } from './route-match.js'
 
 /**
@@ -226,8 +226,12 @@ export default class Website {
   /**
    * Build locales list from config
    * Supports both string codes and objects: ['es', 'fr'] or [{code: 'es', label: 'Español'}]
-   * Labels are passed through if provided; otherwise only code is returned.
-   * Use kit's getLocaleLabel() for display names.
+   * Every returned locale carries a resolved `label`: an explicitly configured
+   * one wins, otherwise it comes from LOCALE_DISPLAY_NAMES, otherwise the code
+   * uppercased. It used to be passed through only when configured, which made
+   * the common foundation idiom `locale.label || locale.code` render "fr"
+   * instead of "Français" for a plain-string `languages:` entry — i.e. the form
+   * locale-config tells authors to migrate to was the one that read worse.
    * @private
    */
   buildLocalesList(config) {
@@ -262,6 +266,7 @@ export default class Website {
     // Build final array with isDefault flag
     return Array.from(localeMap.values()).map(locale => ({
       ...locale,
+      label: localeLabel(locale),
       isDefault: locale.code === defaultLocale
     }))
   }
@@ -857,9 +862,16 @@ export default class Website {
   // ─────────────────────────────────────────────────────────────────
 
   /**
-   * Get all available locales
-   * Label is optional - use kit's getLocaleLabel() for display names if not provided.
-   * @returns {Array<{code: string, label?: string, isDefault: boolean}>}
+   * Get all available locales.
+   *
+   * `label` is always present and always displayable: an explicitly configured
+   * label wins, otherwise it is resolved from LOCALE_DISPLAY_NAMES, otherwise it
+   * is the code uppercased. So `locale.label` needs no fallback at the call site
+   * — the idiom `locale.label || locale.code` is now redundant rather than
+   * load-bearing, and kit's `getLocaleLabel()` is only needed for a code that
+   * did not come from here.
+   *
+   * @returns {Array<{code: string, label: string, isDefault: boolean}>}
    */
   getLocales() {
     return this.locales