@museumwnf/viewer-core 1.14.0 → 1.15.0

package/src/i18n/index.js

@@ -1,88 +1,88 @@
-import { computed, inject, ref } from 'vue'
-
-// The renderers travel with the texts: a package that has only this entry
-// point (@museumwnf/viewer-layout) renders a Markdown prop through the same
-// pipeline as everything else.
-export { md, mdInline, mdStrip, renderBlock, renderInline, renderPlain } from './markdown.js'
-
-// The whole of it: look a key up in the active language, fall back to English,
-// and return the key itself when neither has it, so a missing text shows up as
-// its own name rather than as a blank page.
-//
-// The scope of this module is frozen. It does lookup, fallback and reactivity;
-// it will never grow interpolation, pluralisation or a message format. A text
-// is a text — a value produced at run time is rendered by the component next
-// to the text, never inside it. A future need outside that is a different
-// system, not an extension of this one.
-
-// Symbol.for, not Symbol: this module is reachable through two specifiers —
-// `@museumwnf/viewer-core` (which createViewer imports relatively) and
-// `@museumwnf/viewer-core/i18n` (which viewer-layout imports) — and a bundler
-// that resolves them to two module instances would create two distinct keys.
-// The application would then provide one and the layout inject the other,
-// which reads as "no texts installed" in a package that plainly installed
-// them. A key from the global registry is the same key in every instance.
-export const VIEWER_I18N = Symbol.for('@museumwnf/viewer-core:i18n')
-
-const BASE_LANGUAGE = 'en'
-
-/**
- * Apply the one merge rule of the platform: local wins.
- *
- * Each argument is `{ <language>: { <key>: <text> } }` — the shared bundle
- * first, the website's own file last. Keys carry their namespace, so nothing
- * collides by accident; an entry is overloaded only when a website spells out
- * the same name.
- */
-export function mergeMessages(...catalogues) {
-  const merged = {}
-  for (const catalogue of catalogues) {
-    for (const [language, entries] of Object.entries(catalogue ?? {})) {
-      merged[language] = { ...merged[language], ...entries }
-    }
-  }
-  return merged
-}
-
-export function createI18n({ messages = {}, locale = BASE_LANGUAGE } = {}) {
-  const current = ref(locale)
-
-  const t = (key) => {
-    const active = messages[current.value]
-    if (active && typeof active[key] === 'string') return active[key]
-    const base = messages[BASE_LANGUAGE]
-    if (base && typeof base[key] === 'string') return base[key]
-    return key
-  }
-
-  const i18n = {
-    locale: current,
-    availableLocales: Object.keys(messages),
-    t,
-    install(app) {
-      app.provide(VIEWER_I18N, i18n)
-      // `$t` in a template, `useI18n()` in a script — the two shapes Vue
-      // applications already expect of a translation helper.
-      app.config.globalProperties.$t = t
-    },
-  }
-  return i18n
-}
-
-export function useI18n() {
-  const i18n = inject(VIEWER_I18N, null)
-  if (!i18n) {
-    throw new Error(
-      'useI18n() was called in an application that has no texts installed. ' +
-        'Applications built with createViewer() have them; a test mounting a ' +
-        'component on its own must install createI18n({ messages }) itself.'
-    )
-  }
-  return i18n
-}
-
-/** The active language, for a component that only needs to read it. */
-export function useLocale() {
-  const { locale } = useI18n()
-  return computed(() => locale.value)
-}
+import { computed, inject, ref } from 'vue'
+
+// The renderers travel with the texts: a package that has only this entry
+// point (@museumwnf/viewer-layout) renders a Markdown prop through the same
+// pipeline as everything else.
+export { md, mdInline, mdStrip, renderBlock, renderInline, renderPlain } from './markdown.js'
+
+// The whole of it: look a key up in the active language, fall back to English,
+// and return the key itself when neither has it, so a missing text shows up as
+// its own name rather than as a blank page.
+//
+// The scope of this module is frozen. It does lookup, fallback and reactivity;
+// it will never grow interpolation, pluralisation or a message format. A text
+// is a text — a value produced at run time is rendered by the component next
+// to the text, never inside it. A future need outside that is a different
+// system, not an extension of this one.
+
+// Symbol.for, not Symbol: this module is reachable through two specifiers —
+// `@museumwnf/viewer-core` (which createViewer imports relatively) and
+// `@museumwnf/viewer-core/i18n` (which viewer-layout imports) — and a bundler
+// that resolves them to two module instances would create two distinct keys.
+// The application would then provide one and the layout inject the other,
+// which reads as "no texts installed" in a package that plainly installed
+// them. A key from the global registry is the same key in every instance.
+export const VIEWER_I18N = Symbol.for('@museumwnf/viewer-core:i18n')
+
+const BASE_LANGUAGE = 'en'
+
+/**
+ * Apply the one merge rule of the platform: local wins.
+ *
+ * Each argument is `{ <language>: { <key>: <text> } }` — the shared bundle
+ * first, the website's own file last. Keys carry their namespace, so nothing
+ * collides by accident; an entry is overloaded only when a website spells out
+ * the same name.
+ */
+export function mergeMessages(...catalogues) {
+  const merged = {}
+  for (const catalogue of catalogues) {
+    for (const [language, entries] of Object.entries(catalogue ?? {})) {
+      merged[language] = { ...merged[language], ...entries }
+    }
+  }
+  return merged
+}
+
+export function createI18n({ messages = {}, locale = BASE_LANGUAGE } = {}) {
+  const current = ref(locale)
+
+  const t = (key) => {
+    const active = messages[current.value]
+    if (active && typeof active[key] === 'string') return active[key]
+    const base = messages[BASE_LANGUAGE]
+    if (base && typeof base[key] === 'string') return base[key]
+    return key
+  }
+
+  const i18n = {
+    locale: current,
+    availableLocales: Object.keys(messages),
+    t,
+    install(app) {
+      app.provide(VIEWER_I18N, i18n)
+      // `$t` in a template, `useI18n()` in a script — the two shapes Vue
+      // applications already expect of a translation helper.
+      app.config.globalProperties.$t = t
+    },
+  }
+  return i18n
+}
+
+export function useI18n() {
+  const i18n = inject(VIEWER_I18N, null)
+  if (!i18n) {
+    throw new Error(
+      'useI18n() was called in an application that has no texts installed. ' +
+        'Applications built with createViewer() have them; a test mounting a ' +
+        'component on its own must install createI18n({ messages }) itself.'
+    )
+  }
+  return i18n
+}
+
+/** The active language, for a component that only needs to read it. */
+export function useLocale() {
+  const { locale } = useI18n()
+  return computed(() => locale.value)
+}

package/src/i18n/language.js

@@ -1,127 +1,127 @@
-import { watch } from 'vue'
-import { START_LOCATION } from 'vue-router'
-
-// Which language a visitor gets, decided once, in one place.
-//
-// Before this, a website opened at `languages[0]` and stayed there: no
-// negotiation, no memory between visits, nothing in the URL, and no `lang` or
-// `dir` on the document — so a right-to-left language rendered left to right.
-
-const STORAGE_KEY = 'mwnf.language'
-
-export const RTL_LANGUAGES = new Set([
-  'ar', 'arc', 'ckb', 'dv', 'fa', 'he', 'ku', 'ps', 'sd', 'ug', 'ur', 'yi',
-])
-
-export function isRtl(code) {
-  return RTL_LANGUAGES.has(String(code ?? '').toLowerCase().split('-')[0])
-}
-
-/**
- * The URL first, then the visitor's own earlier choice, then what their
- * browser asks for, then English. A language that is not offered is ignored at
- * every step, so nothing here can select a language the website does not have.
- */
-export function negotiateLanguage(offered, { requested, stored, preferred = [] } = {}) {
-  const list = offered?.length ? offered : ['en']
-  const match = (code) => {
-    if (!code) return undefined
-    const wanted = String(code).toLowerCase()
-    return (
-      list.find((candidate) => candidate.toLowerCase() === wanted) ??
-      list.find((candidate) => candidate.toLowerCase().split('-')[0] === wanted.split('-')[0])
-    )
-  }
-  return (
-    match(requested) ??
-    match(stored) ??
-    preferred.map(match).find(Boolean) ??
-    match('en') ??
-    list[0]
-  )
-}
-
-export function readStoredLanguage() {
-  try {
-    return globalThis.localStorage?.getItem(STORAGE_KEY) ?? null
-  } catch {
-    // A browser refusing storage is not a reason to fail to render a page.
-    return null
-  }
-}
-
-export function storeLanguage(code) {
-  try {
-    globalThis.localStorage?.setItem(STORAGE_KEY, code)
-  } catch {
-    /* see readStoredLanguage */
-  }
-}
-
-export function applyDocumentLanguage(code) {
-  if (typeof document === 'undefined') return
-  document.documentElement.setAttribute('lang', code)
-  document.documentElement.setAttribute('dir', isRtl(code) ? 'rtl' : 'ltr')
-}
-
-function browserLanguages() {
-  if (typeof navigator === 'undefined') return []
-  return navigator.languages ?? (navigator.language ? [navigator.language] : [])
-}
-
-/**
- * The language to start in, before the router has resolved a route. The URL is
- * deliberately not read here — the router owns it, and reading it twice is how
- * the two disagree.
- */
-export function resolveInitialLanguage(offered) {
-  return negotiateLanguage(offered, {
-    stored: readStoredLanguage(),
-    preferred: browserLanguages(),
-  })
-}
-
-/**
- * On a website offering more than one language the URL is the source of truth:
- * `?lang=` carries it, so a page can be linked, bookmarked and shared in the
- * language it was read in. A single-language website never gets the parameter.
- *
- * It is a query parameter rather than a path segment because the legacy routes
- * these websites reproduce are matched by path: prefixing them would break
- * every URL that has ever been published.
- */
-export function connectLanguageToRouter({ locale, offered, router }) {
-  const multilingual = offered.length > 1
-
-  router.beforeEach((to) => {
-    const next = negotiateLanguage(offered, {
-      requested: multilingual ? to.query.lang : undefined,
-      stored: readStoredLanguage(),
-      preferred: browserLanguages(),
-    })
-    if (locale.value !== next) locale.value = next
-    if (multilingual && to.query.lang !== next) {
-      // Resolves on the second pass, when the query already says `next`.
-      return { ...to, query: { ...to.query, lang: next }, replace: true }
-    }
-    return true
-  })
-
-  // A change of language from the switcher rewrites the URL. Not before the
-  // first navigation has resolved, though: the router is then still at its
-  // start location, `/`, and a replace from there cancels the navigation the
-  // visitor arrived with — every deep link landed on the home page. The guard
-  // above puts the language in the URL of that first navigation itself.
-  watch(
-    locale,
-    (code) => {
-      applyDocumentLanguage(code)
-      storeLanguage(code)
-      const current = router.currentRoute.value
-      if (multilingual && current !== START_LOCATION && current.query.lang !== code) {
-        router.replace({ query: { ...current.query, lang: code } })
-      }
-    },
-    { immediate: true }
-  )
-}
+import { watch } from 'vue'
+import { START_LOCATION } from 'vue-router'
+
+// Which language a visitor gets, decided once, in one place.
+//
+// Before this, a website opened at `languages[0]` and stayed there: no
+// negotiation, no memory between visits, nothing in the URL, and no `lang` or
+// `dir` on the document — so a right-to-left language rendered left to right.
+
+const STORAGE_KEY = 'mwnf.language'
+
+export const RTL_LANGUAGES = new Set([
+  'ar', 'arc', 'ckb', 'dv', 'fa', 'he', 'ku', 'ps', 'sd', 'ug', 'ur', 'yi',
+])
+
+export function isRtl(code) {
+  return RTL_LANGUAGES.has(String(code ?? '').toLowerCase().split('-')[0])
+}
+
+/**
+ * The URL first, then the visitor's own earlier choice, then what their
+ * browser asks for, then English. A language that is not offered is ignored at
+ * every step, so nothing here can select a language the website does not have.
+ */
+export function negotiateLanguage(offered, { requested, stored, preferred = [] } = {}) {
+  const list = offered?.length ? offered : ['en']
+  const match = (code) => {
+    if (!code) return undefined
+    const wanted = String(code).toLowerCase()
+    return (
+      list.find((candidate) => candidate.toLowerCase() === wanted) ??
+      list.find((candidate) => candidate.toLowerCase().split('-')[0] === wanted.split('-')[0])
+    )
+  }
+  return (
+    match(requested) ??
+    match(stored) ??
+    preferred.map(match).find(Boolean) ??
+    match('en') ??
+    list[0]
+  )
+}
+
+export function readStoredLanguage() {
+  try {
+    return globalThis.localStorage?.getItem(STORAGE_KEY) ?? null
+  } catch {
+    // A browser refusing storage is not a reason to fail to render a page.
+    return null
+  }
+}
+
+export function storeLanguage(code) {
+  try {
+    globalThis.localStorage?.setItem(STORAGE_KEY, code)
+  } catch {
+    /* see readStoredLanguage */
+  }
+}
+
+export function applyDocumentLanguage(code) {
+  if (typeof document === 'undefined') return
+  document.documentElement.setAttribute('lang', code)
+  document.documentElement.setAttribute('dir', isRtl(code) ? 'rtl' : 'ltr')
+}
+
+function browserLanguages() {
+  if (typeof navigator === 'undefined') return []
+  return navigator.languages ?? (navigator.language ? [navigator.language] : [])
+}
+
+/**
+ * The language to start in, before the router has resolved a route. The URL is
+ * deliberately not read here — the router owns it, and reading it twice is how
+ * the two disagree.
+ */
+export function resolveInitialLanguage(offered) {
+  return negotiateLanguage(offered, {
+    stored: readStoredLanguage(),
+    preferred: browserLanguages(),
+  })
+}
+
+/**
+ * On a website offering more than one language the URL is the source of truth:
+ * `?lang=` carries it, so a page can be linked, bookmarked and shared in the
+ * language it was read in. A single-language website never gets the parameter.
+ *
+ * It is a query parameter rather than a path segment because the legacy routes
+ * these websites reproduce are matched by path: prefixing them would break
+ * every URL that has ever been published.
+ */
+export function connectLanguageToRouter({ locale, offered, router }) {
+  const multilingual = offered.length > 1
+
+  router.beforeEach((to) => {
+    const next = negotiateLanguage(offered, {
+      requested: multilingual ? to.query.lang : undefined,
+      stored: readStoredLanguage(),
+      preferred: browserLanguages(),
+    })
+    if (locale.value !== next) locale.value = next
+    if (multilingual && to.query.lang !== next) {
+      // Resolves on the second pass, when the query already says `next`.
+      return { ...to, query: { ...to.query, lang: next }, replace: true }
+    }
+    return true
+  })
+
+  // A change of language from the switcher rewrites the URL. Not before the
+  // first navigation has resolved, though: the router is then still at its
+  // start location, `/`, and a replace from there cancels the navigation the
+  // visitor arrived with — every deep link landed on the home page. The guard
+  // above puts the language in the URL of that first navigation itself.
+  watch(
+    locale,
+    (code) => {
+      applyDocumentLanguage(code)
+      storeLanguage(code)
+      const current = router.currentRoute.value
+      if (multilingual && current !== START_LOCATION && current.query.lang !== code) {
+        router.replace({ query: { ...current.query, lang: code } })
+      }
+    },
+    { immediate: true }
+  )
+}