@museumwnf/viewer-core 2.9.0 → 2.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@museumwnf/viewer-core",
-  "version": "2.9.0",
+  "version": "2.11.0",
   "description": "Application engine for MWNF websites: turns a dataset.config.js into a mounted Vue application.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE.md",

package/src/catalogue/catalogue.js

@@ -34,15 +34,20 @@ export const CATALOGUE_DATE_MODE = 'overlap'
  * - `itemById`: every item, the visible rule not applied — a page that
  *   deliberately shows a hidden item (a timeline's illustration) reads it.
  *   `partnerById`, `countryById`, `dynastyById`: the visible records.
- * - `itemLabel(item)`, `countryLabel(id)`, `partnerLabel(id)`,
- *   `dynastyLabel(id)`: plain text, `''` for nothing.
+ * - `itemLabel(item)`, `countryLabel(id, lang)`, `partnerLabel(id, lang)`,
+ *   `dynastyLabel(id, lang)`: plain text, `''` for nothing, in `lang` when
+ *   given (the language of the record the name stands next to), in the
+ *   display language otherwise.
  * - `itemRoute(item)`, `partnerRoute(partner)`: the `item` and `partner`
  *   routes by name.
  * - `itemRow(item, meta)`: the row `RecordList`/`RecordGrid`/
  *   `RelatedRecords` share. `meta` lists what follows the name, in order:
  *   `'country'`, `'dates'`, `'location'`, `'dynasties'`, `'holder'` (the
  *   partner's name, only when the package carries the partner, so a label
- *   is never an id), or a function `(item, text) => string`.
+ *   is never an id), or a function `(item, text, lang) => string`. The row
+ *   reads the item in the display language when it has text there, in
+ *   English otherwise, and names its country, dynasties and partner in that
+ *   same language.
  */
 export function useCatalogue(options = {}) {
   const data = useCatalogueData(options)
@@ -59,30 +64,32 @@ export function useCatalogue(options = {}) {
   const dynastyById = data.index('dynasties')
 
   const itemLabel = (item) => (item ? labelOf('items', item.id) : '')
-  const countryLabel = (id) => (id ? labelOf('countries', id) : '')
-  const partnerLabel = (id) => (id ? labelOf('partners', id) : '')
-  const dynastyLabel = (id) => (id ? labelOf('dynasties', id) : '')
+  const countryLabel = (id, lang) => (id ? labelOf('countries', id, { lang }) : '')
+  const partnerLabel = (id, lang) => (id ? labelOf('partners', id, { lang }) : '')
+  const dynastyLabel = (id, lang) => (id ? labelOf('dynasties', id, { lang }) : '')
 
   const itemRoute = (item) => ({ name: 'item', params: { id: item.id } })
   const partnerRoute = (partner) => ({ name: 'partner', params: { id: partner.id } })
 
+  // Each takes the language the row's record is shown in, so its names match it.
   const META = {
-    country: (item) => countryLabel(item.country_id),
+    country: (item, text, lang) => countryLabel(item.country_id, lang),
     dates: (item, text) => text.dates,
     location: (item, text) => text.location,
-    dynasties: (item) => (item.dynasty_ids ?? []).map(dynastyLabel).filter(Boolean).join(', '),
-    holder: (item) => (partnerById.value.has(item.partner_id) ? partnerLabel(item.partner_id) : ''),
+    dynasties: (item, text, lang) => (item.dynasty_ids ?? []).map((id) => dynastyLabel(id, lang)).filter(Boolean).join(', '),
+    holder: (item, text, lang) => (partnerById.value.has(item.partner_id) ? partnerLabel(item.partner_id, lang) : ''),
   }
 
   function itemRow(item, meta = ['country', 'dates']) {
-    const text = tr('items', item.id)
+    const lang = data.languageOf('items', item.id)
+    const text = tr('items', item.id, lang)
     return {
       id: item.id,
       image: item.images?.[0]?.url ?? '',
       imageAlt: itemLabel(item),
       name: mdInline(text.name ?? item.internal_name ?? item.id),
       meta: meta
-        .map((part) => (typeof part === 'function' ? part(item, text) : META[part]?.(item, text)))
+        .map((part) => (typeof part === 'function' ? part(item, text, lang) : META[part]?.(item, text, lang)))
         .filter(Boolean),
       badge: item.type ?? '',
       to: itemRoute(item),

package/src/composables/useCatalogueData.js

@@ -1,4 +1,5 @@
-import { computed } from 'vue'
+import { computed, watch } from 'vue'
+import { displayLanguage } from '../displayLanguage.js'
 import { useDataPackage } from './useDataPackage.js'
 import { byId as coreById, entityRef } from './useEntities.js'
 import { md as coreMd, mdInline as coreMdInline, mdStrip as coreMdStrip } from '../i18n/markdown.js'
@@ -25,10 +26,10 @@ const BASE_LANGUAGE = 'en'
 
 // A term's spellings and definition in one language, falling back to
 // English, then to the term's own headword — the same row shape
-// `useRecordSheet`'s `termRow` builds, but for the whole glossary in
-// `defaultLanguage` rather than one record's `glossary_ids` in the record's
-// own language, which is why it is not reused: a catalogue list or a label
-// is always shown in `defaultLanguage`, a record sheet's text is not.
+// `useRecordSheet`'s `termRow` builds, but for the whole glossary in the
+// display language rather than one record's `glossary_ids` in the record's
+// own language, which is why it is not reused: a catalogue list is shown in
+// the display language, a record sheet in the language the record is read in.
 function glossaryRows(language, translations) {
   const rows = translations('glossary', language)
   const fallback = translations('glossary', BASE_LANGUAGE)
@@ -49,27 +50,46 @@ function glossaryRows(language, translations) {
  * visible form of an entity and its index, and the package re-exports.
  *
  * `eager` names the entities `loadEnglish` loads — every entity the package
- * carries by default. `defaultLanguage` is the language `tr`, the labels and
- * the glossary binding read (`'en'` for every site so far). `visible` names,
+ * carries by default — in `defaultLanguage` and in the display language.
+ * `tr`, the labels and the glossary binding read the display language (the
+ * language the website is shown in, reference data included: a country is
+ * named in the language its record is shown in), and fall back, record by
+ * record, to `defaultLanguage` (`'en'` for every site so far). `visible` names,
  * per entity, the predicate `entity()`/`index()` apply — a per-build
  * language filter, a hidden-partner rule, a display-status check are all
  * "which records this build shows", declared here once instead of coded
  * into every page that lists that entity. `glossary` turns off the default
  * binding on `md`/`mdInline` (a caller may still pass its own `glossary` to
- * either, on or off).
+ * either, on or off). `followDisplayLanguage: false` keeps everything in
+ * `defaultLanguage`, for the DXA families until their pages are checked
+ * against legacy in other languages.
  */
-export function useCatalogueData({ eager, defaultLanguage = BASE_LANGUAGE, visible = {}, glossary = true } = {}) {
+export function useCatalogueData({
+  eager, defaultLanguage = BASE_LANGUAGE, visible = {}, glossary = true, followDisplayLanguage = true,
+} = {}) {
   const pkg = useDataPackage()
   const { availableLanguages, loadTranslations, translations } = pkg
   const eagerEntities = eager ?? pkg.entityNames
+  const shown = computed(() => (followDisplayLanguage ? displayLanguage.value : defaultLanguage))
 
-  /** One record's translated fields, falling back to `defaultLanguage` then `{}`. */
-  function tr(entity, id, lang = defaultLanguage) {
+  /** One record's translated fields, in `lang` (the display language), falling back to `defaultLanguage` then `{}`. */
+  function tr(entity, id, lang = shown.value) {
     return pkg.tr(entity, id, lang, defaultLanguage)
   }
 
+  /**
+   * The language one record is shown in: the display language when the
+   * record has text in it, `defaultLanguage` otherwise. The reference names
+   * shown next to it (its country, its partner, its dynasties) take this
+   * language, so a record left in English is not printed with French names.
+   */
+  function languageOf(entity, id) {
+    const lang = shown.value
+    return id && translations(entity, lang)[id] ? lang : defaultLanguage
+  }
+
   const defaultGlossary = computed(() =>
-    glossary ? glossaryEntries(glossaryRows(defaultLanguage, translations)) : [],
+    glossary ? glossaryEntries(glossaryRows(shown.value, translations)) : [],
   )
 
   // A caller's own `glossary` — a record's own terms, not every term in the
@@ -84,20 +104,34 @@ export function useCatalogueData({ eager, defaultLanguage = BASE_LANGUAGE, visib
   const mdInline = bindGlossary(coreMdInline)
   const mdStrip = coreMdStrip
 
-  /** `mdStrip(tr(entity, id).name ?? record[fallback] ?? id)` — the one label shape every site wrote. */
-  function labelOf(entity, id, { fallback = 'internal_name' } = {}) {
+  /**
+   * `mdStrip(tr(entity, id, lang).name ?? record[fallback] ?? id)` — the one
+   * label shape every site wrote. `lang` is the display language unless the
+   * caller names the language of the record the label stands next to.
+   */
+  function labelOf(entity, id, { fallback = 'internal_name', lang } = {}) {
     if (!id) return ''
-    const name = tr(entity, id).name
+    // A label passed as a callback (`.map(countryLabel)`, a facet's
+    // `label(value, ctx)`) receives an index or a context here, not a language.
+    const name = tr(entity, id, typeof lang === 'string' ? lang : undefined).name
     if (name) return mdStrip(name)
     const record = coreById(entity).value.get(id)
     return mdStrip(record?.[fallback] ?? id)
   }
 
   let englishReady = null
-  /** Loads `defaultLanguage` for every entity in `eager`, once. */
+  /**
+   * Loads `defaultLanguage` for every entity in `eager`, once, and the display
+   * language too, again each time it changes. Resolves with the
+   * `defaultLanguage` files: a page renders in English until the other
+   * language arrives, and re-renders then.
+   */
   function loadEnglish() {
     if (!englishReady) {
       englishReady = Promise.all(eagerEntities.map((name) => loadTranslations(name, defaultLanguage)))
+      watch(shown, (lang) => {
+        if (lang !== defaultLanguage) eagerEntities.forEach((name) => loadTranslations(name, lang))
+      }, { immediate: true })
     }
     return englishReady
   }
@@ -135,7 +169,7 @@ export function useCatalogueData({ eager, defaultLanguage = BASE_LANGUAGE, visib
   }
 
   return {
-    tr, md, mdInline, mdStrip, loadEnglish, labelOf, entity, index,
+    tr, md, mdInline, mdStrip, loadEnglish, labelOf, languageOf, entity, index,
     availableLanguages, loadTranslations, translations,
   }
 }

package/src/createViewer.js

@@ -1,6 +1,7 @@
 import { createApp } from 'vue'
 import AppRoot from './AppRoot.vue'
 import { useDataPackage } from './composables/useDataPackage.js'
+import { bindDisplayLanguage } from './displayLanguage.js'
 import { createI18n } from './i18n/index.js'
 import { connectLanguageToRouter, resolveInitialLanguage } from './i18n/language.js'
 import { VIEWER_CONFIG } from './injectionKeys.js'
@@ -24,6 +25,7 @@ export function createViewer(config = {}) {
   app.use(i18n)
 
   connectLanguageToRouter({ locale: i18n.locale, offered: languages, router })
+  bindDisplayLanguage(i18n.locale)
 
   return app
 }

package/src/displayLanguage.js

@@ -0,0 +1,18 @@
+import { computed, shallowRef } from 'vue'
+
+// The language the website is shown in, for code that runs outside a
+// component: the catalogue data layer is built once, at module scope, where
+// `useI18n()` cannot inject. `createViewer` binds the application's locale
+// here, the way it hands its configuration to `setSiteConfig`; until it does
+// (a test mounting one component), the website is in English.
+
+const BASE_LANGUAGE = 'en'
+const bound = shallowRef(null)
+
+/** The active display language, read-only. */
+export const displayLanguage = computed(() => bound.value?.value ?? BASE_LANGUAGE)
+
+/** Binds the application's locale ref; `createViewer` calls it once. */
+export function bindDisplayLanguage(locale) {
+  bound.value = locale ?? null
+}

package/src/dxa/exhibition/useExhibitionData.js

@@ -61,6 +61,9 @@ export function useExhibitionData(config = {}) {
 
   const catalogue = useCatalogueData({
     eager: config.eager ?? DEFAULT_EAGER,
+    // English-first until these pages are checked against legacy in other
+    // languages (the display-language rule, inventory-app#2414).
+    followDisplayLanguage: false,
     defaultLanguage: defaultLang,
     visible: {
       // An item's `languages` is what it has TRANSLATIONS in, so a

package/src/dxa/exhibition/useExhibitionSheet.js

@@ -27,7 +27,7 @@
 // dynasties stand in when it has none, and keep their own popouts
 // (decision D5, inventory-app#2233).
 
-import { artistLine, pictureCredits, recordArtist } from '../../record/derivations.js'
+import { artistLine, pictureCredits, picturesInLanguage, recordArtist } from '../../record/derivations.js'
 
 /**
  * The exhibition's item-sheet spec, over its data layer's `data`.
@@ -88,13 +88,17 @@ export function useExhibitionSheet(data, config = {}) {
     entity: 'items',
     translations: ['glossary', 'dynasties', 'partners'],
     // Credits are the sheet language's own: dxa-api read them from that
-    // language's authors_objects rows and printed nothing when it had none.
+    // language's authors_objects rows (else the record's own credit column)
+    // and printed nothing when it had neither. Each person is printed as its
+    // SQL did, "Firstname LASTNAME" (`credit_names`, `creditLine`).
+    creditNames: true,
     fields,
     layout: 'list',
     shortDescription: 'short_description',
     shortDescriptionAfter: 'description',
+    // Only the pictures with a row in the sheet's language, as dxa-api listed them.
     media: (record, { language }) =>
-      [...(record.images ?? [])]
+      [...picturesInLanguage(record.images, language)]
         .sort((a, b) => (a.display_order ?? 0) - (b.display_order ?? 0))
         .map((p) => ({
           url: p.url,

package/src/dxa/gallery/useGalleryData.js

@@ -28,6 +28,9 @@ export function useGalleryData(config = {}) {
 
   const catalogue = useCatalogueData({
     eager: config.eager ?? DEFAULT_EAGER,
+    // English-first until these pages are checked against legacy in other
+    // languages (the display-language rule, inventory-app#2414).
+    followDisplayLanguage: false,
   })
 
   const {

package/src/dxa/gallery/useGallerySheet.js

@@ -27,7 +27,7 @@
 // dynasties stand in when it has none, and keep their own popouts
 // (decision D5, inventory-app#2233).
 
-import { artistLine, pictureCredits, recordArtist } from '../../record/derivations.js'
+import { artistLine, pictureCredits, picturesInLanguage, recordArtist } from '../../record/derivations.js'
 
 /**
  * The gallery's item-sheet spec, over its data layer's `data`.
@@ -88,13 +88,17 @@ export function useGallerySheet(data, config = {}) {
     entity: 'items',
     translations: ['glossary', 'dynasties', 'partners'],
     // Credits are the sheet language's own: dxa-api read them from that
-    // language's authors_objects rows and printed nothing when it had none.
+    // language's authors_objects rows (else the record's own credit column)
+    // and printed nothing when it had neither. Each person is printed as its
+    // SQL did, "Firstname LASTNAME" (`credit_names`, `creditLine`).
+    creditNames: true,
     fields,
     layout: 'list',
     shortDescription: 'short_description',
     shortDescriptionAfter: 'description',
+    // Only the pictures with a row in the sheet's language, as dxa-api listed them.
     media: (record, { language }) =>
-      [...(record.images ?? [])]
+      [...picturesInLanguage(record.images, language)]
         .sort((a, b) => (a.display_order ?? 0) - (b.display_order ?? 0))
         .map((p) => ({
           url: p.url,

package/src/i18n/markdown.js

@@ -30,6 +30,27 @@ const escaping = {
   },
 }
 
+// No text on these websites is code. Legacy wrote the backtick as a letter
+// (the ʿayn of "Fu`ad", "`Abbas"), and a text pasted from a word processor can
+// hold one anywhere; read as Markdown, two of them turned the words between
+// into a code span, printed in a code font with any markup inside as
+// characters. An indented line was a code block the same way. Without these
+// three tokenizers a backtick is the character it is, and an indented line a
+// line of its paragraph.
+const noCode = {
+  tokenizer: {
+    codespan() {
+      return undefined
+    },
+    code() {
+      return undefined
+    },
+    fences() {
+      return undefined
+    },
+  },
+}
+
 // `breaks` is the one difference, and it is a difference in the source rather
 // than in policy. A text in the dictionary is written as prose and wraps freely,
 // so a single newline means nothing. A record's field arrives from a database
@@ -37,8 +58,8 @@ const escaping = {
 // together.
 const prose = new Marked({ async: false, gfm: true, breaks: false })
 const record = new Marked({ async: false, gfm: true, breaks: true })
-prose.use(escaping)
-record.use(escaping)
+prose.use(escaping, noCode)
+record.use(escaping, noCode)
 
 const pipeline = (breaks) => (breaks ? record : prose)
 
@@ -123,8 +144,8 @@ function withGlossary(breaks, glossary) {
     } else {
       const withProse = new Marked({ async: false, gfm: true, breaks: false })
       const withRecord = new Marked({ async: false, gfm: true, breaks: true })
-      withProse.use(escaping, { extensions: [extension] })
-      withRecord.use(escaping, { extensions: [extension] })
+      withProse.use(escaping, noCode, { extensions: [extension] })
+      withRecord.use(escaping, noCode, { extensions: [extension] })
       entry = { prose: withProse, record: withRecord }
     }
     glossaryPipelines.set(key, entry)

package/src/index.js

@@ -17,6 +17,7 @@ export { md, mdInline, mdStrip, renderBlock, renderInline, renderPlain } from '.
 export { languageLabels, offeredLanguages } from './languages.js'
 export { defaultScrollBehavior, resolveViews } from './router/index.js'
 export { mediaUrl, useSiteConfig } from './siteConfig.js'
+export { bindDisplayLanguage, displayLanguage } from './displayLanguage.js'
 export { sourceUrl, useSiteRights } from './rights.js'
 
 // The list pages: query state, pagination, facets, dates, keyword search.
@@ -39,7 +40,7 @@ export {
   glossaryEntries, glossaryTermsFor, glossaryTermsForText, sheetRows, useRecordSheet,
 } from './record/recordSheet.js'
 export {
-  artistLine, citation, pictureCredits, recordArtist, relatedRecords, removeEndingPoint, searchGlossary, timelineLinkFor, useGlossaryPopup,
+  artistLine, citation, creditLine, pictureCredits, picturesInLanguage, recordArtist, relatedRecords, removeEndingPoint, searchGlossary, timelineLinkFor, useGlossaryPopup,
   useRelatedRecords,
 } from './record/derivations.js'
 export { buildCollectionTree, collectionTreeFromThemes, useCollectionTree } from './record/collectionTree.js'

package/src/record/derivations.js

@@ -193,6 +193,33 @@ export function pictureCredits(picture, language) {
   return { photographer: picture?.photographer ?? '', copyright: picture?.copyright ?? '' }
 }
 
+/**
+ * The pictures a page in `language` shows. Legacy listed a picture on a page
+ * only where it had a row in that language, empty or not; a package carries
+ * those languages per picture (`languages`). A package exported before them
+ * has no such list, and every picture shows, as before.
+ */
+export function picturesInLanguage(pictures, language) {
+  return (pictures ?? []).filter((picture) => !Array.isArray(picture?.languages) || picture.languages.includes(language))
+}
+
+/**
+ * A credit line from its people (`credit_names[role]` in a package): each one
+ * as the galleries' sheet printed them, "Firstname LASTNAME" (dxa-api's SQL
+ * capitalised the surname; the data keeps it as written), or as written when
+ * the entry is a spelling of its own (`{ name }`: the original script on an
+ * Arabic page, or the record's own credit column). Joined with ", ".
+ */
+export function creditLine(names) {
+  return (names ?? [])
+    .map((entry) => {
+      if (typeof entry?.name === 'string') return entry.name.trim()
+      return [entry?.firstname?.trim(), entry?.lastname?.trim()?.toLocaleUpperCase()].filter(Boolean).join(' ')
+    })
+    .filter(Boolean)
+    .join(', ')
+}
+
 const lifePart = (value) => (typeof value === 'string' ? value.trim() : '')
 
 /**