@museumwnf/viewer-core 1.14.0

package/src/composables/useEntities.js

@@ -0,0 +1,100 @@
+import { computed, shallowRef } from 'vue'
+import { useDataPackage } from './useDataPackage.js'
+
+// The records of an entity are one thing: loaded once, from the chunk Vite
+// emits for that one file, and shared by every page that asks for them. A
+// website reads them through here and keeps no copy of its own — the alias
+// `@inventory-data` is this package's, and a site file importing from it
+// directly ships the whole dataset in its first bundle.
+
+const records = new Map() // entity name → shallowRef(null | records)
+const pending = new Map() // entity name → the load in flight
+const indexes = new Map() // `${entity}.${key}` → computed Map
+
+function refFor(name) {
+  let entry = records.get(name)
+  if (!entry) {
+    entry = shallowRef(null)
+    records.set(name, entry)
+  }
+  return entry
+}
+
+/**
+ * The shared ref of one entity, without asking for its load — `null` until a
+ * route's `meta.entities` or `loadEntities` brings the chunk in. This is what
+ * a website's data composable exports at module level, so that importing the
+ * composable loads nothing: the pages that read an entity are the ones that
+ * declare it.
+ */
+export function entityRef(name) {
+  return refFor(name)
+}
+
+/**
+ * Load the named entities, once each. Resolves with their records in the
+ * order asked for; a name the package does not have rejects, as `loadEntity`
+ * does.
+ */
+export function loadEntities(names) {
+  const { loadEntity } = useDataPackage()
+  return Promise.all(
+    names.map((name) => {
+      const entry = refFor(name)
+      if (entry.value !== null) return entry.value
+      let load = pending.get(name)
+      if (!load) {
+        load = loadEntity(name)
+          .then((data) => {
+            entry.value = data
+            pending.delete(name)
+            return data
+          })
+          .catch((error) => {
+            pending.delete(name)
+            throw error
+          })
+        pending.set(name, load)
+      }
+      return load
+    }),
+  )
+}
+
+/**
+ * A record map for one entity, keyed on `key` (the package id by default) —
+ * empty until the entity is loaded, and rebuilt if it ever reloads.
+ */
+export function byId(name, key = 'id') {
+  const cacheKey = `${name}.${key}`
+  let index = indexes.get(cacheKey)
+  if (!index) {
+    const entry = refFor(name)
+    index = computed(() => new Map((entry.value ?? []).map((record) => [record[key], record])))
+    indexes.set(cacheKey, index)
+  }
+  return index
+}
+
+/**
+ * The standard way a website reads its records.
+ *
+ * `useEntities(['items', 'partners'])` returns one reactive ref per name —
+ * `null` until that entity's chunk has arrived, the records after — plus
+ * `ready`, a promise for all of them, `loaded`, the same as a boolean, and
+ * `byId`. The refs are the same objects for every caller, so a composable
+ * may export them at module level and a view may read them at any time.
+ *
+ * A route that declares `meta: { entities: [...] }` has them loaded by the
+ * router before its view is created, so that view never sees `null`.
+ */
+export function useEntities(names) {
+  const list = Array.isArray(names) ? names : [names]
+  const result = { ready: loadEntities(list) }
+  for (const name of list) {
+    result[name] = refFor(name)
+  }
+  result.loaded = computed(() => list.every((name) => refFor(name).value !== null))
+  result.byId = byId
+  return result
+}

package/src/composables/useRecordLanguage.js

@@ -0,0 +1,71 @@
+import { computed, ref, toValue, watch } from 'vue'
+import { useI18n } from '../i18n/index.js'
+import { isRtl } from '../i18n/language.js'
+import { useDataPackage } from './useDataPackage.js'
+
+const BASE_LANGUAGE = 'en'
+
+/**
+ * The language a record is read in, given the languages it carries and the
+ * language the website is in: the site language when the record has it,
+ * English when it does not, the record's first language when it has neither.
+ */
+export function resolveRecordLanguage(languages, siteLanguage) {
+  const carried = languages ?? []
+  if (carried.length === 0) return siteLanguage
+  return (
+    carried.find((code) => code === siteLanguage) ??
+    carried.find((code) => code === BASE_LANGUAGE) ??
+    carried[0]
+  )
+}
+
+/**
+ * The site language and the record language are two different things. The
+ * site language is negotiated once and holds for the whole visit; a record
+ * may carry languages the site does not offer, and the visitor may read the
+ * record they are on in any of them. That choice is view state: it is not in
+ * the URL, it does not touch the site language, and it is forgotten when the
+ * site language changes or another record is shown.
+ *
+ * `record` is a ref, a computed or a getter to the record; its `languages`
+ * field says what it carries. A record without one carries every language
+ * `entity` has a translation file for, when `entity` is given; `languages`
+ * (a getter) overrides both.
+ */
+export function useRecordLanguage(record, { entity, languages: given } = {}) {
+  const { locale } = useI18n()
+  const { availableLanguages } = useDataPackage()
+
+  const languages = computed(() => {
+    const own = given ? toValue(given) : toValue(record)?.languages
+    if (Array.isArray(own) && own.length > 0) return own
+    return entity ? availableLanguages(entity) : []
+  })
+
+  const chosen = ref(null)
+  const language = computed(() =>
+    chosen.value && languages.value.includes(chosen.value)
+      ? chosen.value
+      : resolveRecordLanguage(languages.value, locale.value),
+  )
+  const dir = computed(() => (isRtl(language.value) ? 'rtl' : 'ltr'))
+
+  function select(code) {
+    if (languages.value.includes(code)) chosen.value = code
+  }
+  function reset() {
+    chosen.value = null
+  }
+
+  watch(locale, reset)
+  watch(
+    () => {
+      const current = toValue(record)
+      return current?.id ?? current
+    },
+    reset,
+  )
+
+  return { language, languages, dir, select, reset }
+}

package/src/conventions.js

@@ -0,0 +1,148 @@
+import { computed, toValue } from 'vue'
+import { useRoute } from 'vue-router'
+import { useI18n } from './i18n/index.js'
+import { entityRef } from './composables/useEntities.js'
+
+// Three small conventions each website had written for itself.
+
+// ── Project names ──────────────────────────────────────────────────────────
+//
+// `mwnf3.projectnames`, the whole table rather than the projects a website
+// happens to borrow from, since that set moves with every reimport. The key
+// on the left is data; the entry on the right is a shared text
+// (`core.project.*` in viewer-i18n), written out so a reader can see the
+// eight this asks for. A key that is not here reads as itself.
+export const PROJECT_ENTRIES = Object.freeze({
+  ISL: 'core.project.islamicArt',
+  EPM: 'core.project.explorePartners',
+  DBA: 'core.project.baroqueArt',
+  BAR: 'core.project.baroqueArt',
+  AWE: 'core.project.sharingHistory',
+  awe: 'core.project.sharingHistory',
+  DCA: 'core.project.carpetArt',
+  DGA: 'core.project.glassArt',
+  EXTHE: 'core.project.tableIsSet',
+  GALLERIES: 'core.project.galleries',
+})
+
+/** The name of a project by its legacy key, through `t`; the key itself when unknown. */
+export function projectName(key, t) {
+  const entry = PROJECT_ENTRIES[key]
+  return entry ? t(entry) : (key ?? '')
+}
+
+/** `projectName` bound to the installed texts, for a component. */
+export function useProjectName() {
+  const { t } = useI18n()
+  return (key) => projectName(key, t)
+}
+
+// A member is borrowed from the MWNF project that originally published it,
+// and legacy names and colours that project on the item sheet and in the
+// results grid — two separate mappings, because legacy keeps them separate:
+// the name is per project key (`PROJECT_ENTRIES` above), the colour is per
+// project *family*, so ISL and EPM share a swatch and every exhibition
+// shares another. The two exhibition sites re-hard-coded this table as
+// English literals next to their own copy of the name table, which is why a
+// project name translates on the galleries and not on the exhibitions.
+export const PROJECT_FAMILIES = Object.freeze({
+  ISL: 'ISLandEPM',
+  EPM: 'ISLandEPM',
+  DBA: 'DBA',
+  BAR: 'DBA',
+  AWE: 'AWE',
+  awe: 'AWE',
+  DCA: 'DCA',
+  DGA: 'DGA',
+  EXTHE: 'EXH',
+  GALLERIES: 'Galleries',
+})
+
+/** A project's family by its legacy key — legacy's own class names, so a
+ * site's CSS reads as the stylesheet it was copied from. A key with no
+ * entry falls back to itself, the same rule `projectName` applies. */
+export function projectFamily(key) {
+  return PROJECT_FAMILIES[key] ?? (key ?? '')
+}
+
+// ── The section a route belongs to ─────────────────────────────────────────
+//
+// A route says what section it is (`meta: { section: 'collection' }`), and
+// the shell reads it here for the banner title or the active menu entry.
+// Four shells derived the same thing from `route.path.startsWith(…)` chains
+// of nine branches each; a route already knows.
+export function useSection() {
+  const route = useRoute()
+  return computed(() => String(route.meta?.section ?? ''))
+}
+
+// ── A featured record ──────────────────────────────────────────────────────
+
+// mulberry32 — a small seedable generator, so a test can pin the pick.
+function seeded(seed) {
+  let a = seed >>> 0
+  return () => {
+    a = (a + 0x6d2b79f5) >>> 0
+    let t = a
+    t = Math.imul(t ^ (t >>> 15), t | 1)
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61)
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296
+  }
+}
+
+/**
+ * One record of `entity` chosen at random for a landing page's spotlight —
+ * among those with an image when `withImage` is set (the default), among
+ * all when none has one. Null until the entity is loaded. The pick is made
+ * once per visit and again only when the records change; `seed` makes it
+ * deterministic.
+ */
+export function useFeaturedRecord(entity, { withImage = true, seed, images = 'images' } = {}) {
+  const records = entityRef(entity)
+  const random = seed == null ? Math.random : seeded(seed)
+  return computed(() => {
+    const all = toValue(records) ?? []
+    if (all.length === 0) return null
+    const pool = withImage ? all.filter((record) => (record?.[images]?.length ?? 0) > 0) : all
+    const candidates = pool.length > 0 ? pool : all
+    return candidates[Math.floor(random() * candidates.length)] ?? null
+  })
+}
+
+// ── A route's `meta.entities` ────────────────────────────────────────────
+
+/**
+ * `sectionMeta(chrome)` returns a `meta(section, ...entities)` helper: a
+ * route's `meta: { section, entities: [...chrome, ...entities] }` in one
+ * call. `chrome` is the entities every page of the site loads regardless of
+ * what it is (the DXA sites' `['gallery', 'items', 'partners', 'countries']`
+ * — the shell reads them on every route); a route names on top of that only
+ * the entities its own page adds. Four DXA configs each wrote this same
+ * four-line closure next to their own `chrome` list.
+ */
+export function sectionMeta(chrome = []) {
+  return (section, ...entities) => ({ section, entities: [...chrome, ...entities] })
+}
+
+// ── The MWNF portal ─────────────────────────────────────────────────────
+
+/**
+ * The addresses every DXA `dataset.config.js` repeats under `links` —
+ * the portal and the sibling standalone sites a gallery or an exhibition
+ * links out to. Frozen: a site's own `links` may add to this object but
+ * copying it is what this replaces.
+ */
+export const mwnfLinks = Object.freeze({
+  portal: 'https://www.museumwnf.org',
+  galleries: 'https://galleries.museumwnf.org',
+  myCollection: 'https://www.museumwnf.org/mycollection/index.php',
+  about: 'https://www.museumwnf.org/about',
+  contact: 'https://www.museumwnf.org/about/contact',
+  legalNotice: 'https://www.museumwnf.org/about/legal-notice',
+  credits: 'https://www.museumwnf.org/about/credits',
+  cookies: 'https://www.museumwnf.org/about/cookies',
+  overallDatabase: 'https://www.museumwnf.org/database_searchform.php',
+  islamicArt: 'https://islamicart.museumwnf.org',
+  baroqueArt: 'https://baroqueart.museumwnf.org',
+  sharingHistory: 'https://sharinghistory.museumwnf.org',
+})

package/src/createViewer.js

@@ -0,0 +1,29 @@
+import { createApp } from 'vue'
+import AppRoot from './AppRoot.vue'
+import { useDataPackage } from './composables/useDataPackage.js'
+import { createI18n } from './i18n/index.js'
+import { connectLanguageToRouter, resolveInitialLanguage } from './i18n/language.js'
+import { VIEWER_CONFIG } from './injectionKeys.js'
+import { createViewerRouter } from './router/index.js'
+import { setSiteConfig } from './siteConfig.js'
+import './styles/base.css'
+
+export function createViewer(config = {}) {
+  const { languages: datasetLanguages } = useDataPackage()
+  const languages = config.languages ?? datasetLanguages
+  const messages = config.messages ?? {}
+  const resolved = { ...config, languages }
+
+  const router = createViewerRouter(config)
+  const i18n = createI18n({ messages, locale: resolveInitialLanguage(languages) })
+
+  const app = createApp(AppRoot)
+  setSiteConfig(resolved)
+  app.provide(VIEWER_CONFIG, resolved)
+  app.use(router)
+  app.use(i18n)
+
+  connectLanguageToRouter({ locale: i18n.locale, offered: languages, router })
+
+  return app
+}

package/src/i18n/I18nText.vue

@@ -0,0 +1,17 @@
+<script setup>
+import { computed } from 'vue'
+import { useI18n } from './index.js'
+import { renderBlock } from './markdown.js'
+
+const props = defineProps({
+  keypath: { type: String, required: true },
+  tag: { type: String, default: 'div' },
+})
+
+const { t } = useI18n()
+const html = computed(() => renderBlock(t(props.keypath)))
+</script>
+
+<template>
+  <component :is="tag" class="vc-text" v-html="html" />
+</template>

package/src/i18n/I18nTextInline.vue

@@ -0,0 +1,17 @@
+<script setup>
+import { computed } from 'vue'
+import { useI18n } from './index.js'
+import { renderInline } from './markdown.js'
+
+const props = defineProps({
+  keypath: { type: String, required: true },
+  tag: { type: String, default: 'span' },
+})
+
+const { t } = useI18n()
+const html = computed(() => renderInline(t(props.keypath)))
+</script>
+
+<template>
+  <component :is="tag" class="vc-text-inline" v-html="html" />
+</template>

package/src/i18n/index.js

@@ -0,0 +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)
+}

package/src/i18n/language.js

@@ -0,0 +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 }
+  )
+}