@museumwnf/viewer-core 2.0.0 → 2.1.0

package/README.md

@@ -11,6 +11,29 @@ Texts are handled here, without an i18n library: see [Texts](#texts). Nothing in
 the platform depends on `vue-i18n` any more, and this package no longer asks for
 it.
 
+## Entry points and layers
+
+Each entry point belongs to one layer of the platform's
+[architecture reference](https://github.com/museumwithnofrontiers/inventory-app/issues/1510), which says what goes where across
+all the packages:
+
+| Entry | Layer | Holds |
+| --- | --- | --- |
+| `@museumwnf/viewer-core` | engine and data layer | the application factory, the router and the texts runtime; the **data layer** — how a site reads its data package ([records](#records-useentities-the-standard-way-a-website-reads-them), [a website's data composable](#a-websites-data-composable), [`useDataPackage`](#usedatapackage--data-access-the-only-allowed-way-to-read-the-data-package)); the engines of list pages, timelines and record pages; the view-model builders the blocks of `@museumwnf/viewer-layout` are fed with ([record pages](#record-pages), [collection trees](#collection-trees), [partners](#partners)) |
+| `@museumwnf/viewer-core/dxa` | DXA family layer | the data composables of the gallery and the exhibition families ([below](#museumwnfviewer-coredxa)) |
+| `@museumwnf/viewer-core/legacy` | legacy address mapping | pure functions decoding `backward_compatibility` for legacy URL shapes |
+| `@museumwnf/viewer-core/testing` | a website's tests | the shared smoke-test kit ([Testing a website](#testing-a-website)) |
+| `@museumwnf/viewer-core/vite` | a website's build | `defineViewerConfig` |
+
+The root is generic: every kind of website reads its data through it — the
+standalone products, the scaffold of `website-template`, and the DXA
+family's own composables. A composable only the galleries or the
+exhibitions use belongs under `/dxa`, never in the root. The dependency runs
+one way: the root, `/legacy`, `/testing` and `/vite` never import from
+`/dxa`, and `/dxa` builds only on what the root and `/legacy` publish. A
+function that moves between entries keeps its old export as an alias until
+the websites have moved; a major release then removes it.
+
 ## Install
 
 Published to npmjs (`registry.npmjs.org`), publicly — no authentication needed
@@ -447,6 +470,7 @@ under the main partner it belongs to.
 | --- | --- |
 | `groupByCountry(records, { label, tier?, order = 'asc' })` | `[{ country, label, main, associated }]`, one entry per distinct `country_id`, sorted by `label`. `label(country)` names a group's country, the same shape as a facet's `label(value)`. `tier` names the field that marks a main partner (the converged shape's `level`); a record is associated only when its tier value is a non-empty value other than `'partner'` (legacy values: `'associated_partner'`, `'minor_contributor'`); `null`, `undefined`, `''`, or `'partner'` mean main. Without a `tier` every record is main, which is the DXA lists' plain grouping. Partners keep the order `records` was given in within each tier. |
 | `partnerHierarchy(partners)` | `{ children(id), parentOf(id), roots }` from `parent_id`: `children(id)` a partner's associated partners, `parentOf(id)` the main partner it belongs to (or null), `roots` every partner with no parent in the list or whose `parent_id` points outside it. |
+| `partnerView(partner, text, ctx)` | The view-model every rendering of one partner reads — `@museumwnf/viewer-layout`'s `PartnerPanel` in each of its variants: `{ id, type, name (inline HTML), plainName, city, country, location, logos: [{ url, alt, type }], pictures: [{ url, alt, caption, photographer, copyright }], description (block HTML), contact: { address (block HTML), phone, fax, email, website: { url, label } \| null, links: [{ url, label }] }, persons: [{ title, name, phone, fax, email }], hasContact, map: { latitude, longitude, zoom, label } \| null, itemCount, hidden, route, objectsRoute }`. `text` is the partner's translation in the language shown. `ctx` carries only what differs by family: `countryLabel(id)`, the renderers (`md`, `mdInline`, `mdStrip`, the package's by default), `route(partner)`, `objectsRoute(partner)` and `hidden(partner)` (a hidden partner keeps its name and loses both links). Contact persons come from `contact_persons`, in order, keeping those with a name or a title. A picture's caption is its `alt_text`. A website or link with no scheme gets `https://`; any scheme other than `http(s)` is dropped. |
 
 ### Conventions
 
@@ -494,16 +518,21 @@ needs it; the standalone sites never import it.
 
 ### `@museumwnf/viewer-core/dxa`
 
-The gallery/exhibition-pair composables the four live DXA sites each wrote
-for themselves — `useCollection`/`useGalleryData`, the timeline, the
-partner specs and the item sheet — byte-identical within each pair
-(carpets/amulets — a gallery; the-use-of-colours-in-art/water-in-islam — an
-exhibition). Promoted here per family, never as one composable that papers
-over the two: the cross-family diff is real behaviour (the exhibition
-shape's per-language-build 404 gate, its own local-vs-country timeline
-switch, its manifest-driven citation line), confirmed file by file against
-both pairs' `origin/main` (epic metanull/inventory-app#1730). A separate
-entry point because only a gallery/exhibition site needs it.
+This entry is the data half of the DXA family layer; the family's pages are
+in `@museumwnf/viewer-layout/dxa`. The galleries are one site with different
+data, and so are the exhibitions — the legacy served each family from one
+application — so what is the same on every site of a family lives here
+once instead of in each site.
+
+What may go here: a composable or a constant that only the gallery or the
+exhibition family uses, and that is the same on every site of that family,
+including the data instance each site of the family builds from these
+composables. Each family keeps its own composables, never one that papers
+over the two: the difference between the families is real behaviour (the
+exhibition's per-language-build 404 gate, its own local-vs-country timeline
+switch, its manifest-driven citation line). A difference between two sites
+of one family is a `config` value, not a copy. Nothing outside `/dxa`
+imports from it; it builds only on what the root and `/legacy` publish.
 
 A site composes its own data/catalogue/timeline/partner/sheet module from
 these, threading the `data` object one family's
@@ -724,12 +753,12 @@ The package exports shared smoke-test helpers at @museumwnf/viewer-core/testing:
 | checkRoutes(config, { names, legacyPaths }) | Verify every route has a name, no route is a catch-all, and expected names and legacy paths are present. Returns the list of problems found. |
 | checkSectionMeta(config) | Verify every route has a meta.section string (used by the menu to highlight the current page). Returns the list of problems found. |
 | checkTextsRendered(host, { namespaces }) | Match text keys in the rendered host against a regex like /\b(ns1\|ns2)\.[a-z]/i. Returns the list of namespaces found (empty if none). |
-| defineViewerConfig({ dataPackage, inline, plugins, root }) | Return a Vite config object the seven websites share: the @inventory-data alias, optimizeDeps to inline viewer packages, testTimeout of 60s, and the test environment. Exported from `@museumwnf/viewer-core/vite` for use in `vite.config.js` (separate entry because Vite's config loader runs under Node.js, which cannot parse `.vue` files; the `/testing` barrel reaches a `.vue` file). dataPackage is the npm package name; inline is an optional array of extra packages; plugins is the Vite plugins array (e.g. @vitejs/plugin-vue); root is the project root path (default `process.cwd()`), used to resolve the data package from the project root. |
+| defineViewerConfig({ dataPackage, inline, plugins, root }) | Return the Vite config object every website shares: the @inventory-data alias, optimizeDeps to inline viewer packages, testTimeout of 60s, and the test environment. Exported from `@museumwnf/viewer-core/vite` for use in `vite.config.js` (separate entry because Vite's config loader runs under Node.js, which cannot parse `.vue` files; the `/testing` barrel reaches a `.vue` file). dataPackage is the npm package name; inline is an optional array of extra packages; plugins is the Vite plugins array (e.g. @vitejs/plugin-vue); root is the project root path (default `process.cwd()`), used to resolve the data package from the project root. |
 | checkOfferedLanguages(config) | Check that the website offers only languages with content, in the declared order, with labels on the switcher. Returns the list of problems found. |
 
 @museumwnf/viewer-core/testing is not imported by websites, only by their tests. A website test might be:
 
-\\\js
+```js
 import { checkOfferedLanguages, checkRoutes, checkSectionMeta, mountSite } from '@museumwnf/viewer-core/testing'
 import config from '../src/dataset.config.js'
 import { mergeMessages } from '@museumwnf/viewer-core'
@@ -747,7 +776,8 @@ describe('smoke test', () => {
     app.unmount()
   })
 })
-\\\
+```
+
 ## Licence
 
 This package is Content of the MWNF Website under the [MWNF legal
@@ -759,5 +789,10 @@ notice text also ships in this package as `LICENSE.md`.
 ## Release procedure
 
 1. Merge to `main` via PR (CI: tests + a downstream build of every website).
-2. Create a GitHub release with tag `vX.Y.Z` — CI publishes to GitHub Packages; never publish from a laptop.
+2. Create a GitHub release with tag `vX.Y.Z` — CI publishes to npmjs through
+   trusted publishing; never publish from a laptop.
 3. Semver rules: **patch** = fix; **minor** = backward-compatible addition; **major** = breaking change (breaking = any change requiring an edit in a consuming website).
+
+Websites receive a release through the platform's propagation run — see
+[MAINTENANCE.md](https://github.com/museumwithnofrontiers/viewer-workflows/blob/main/MAINTENANCE.md)
+in `viewer-workflows`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@museumwnf/viewer-core",
-  "version": "2.0.0",
+  "version": "2.1.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/dxa/exhibition/useExhibitionSheet.js

@@ -45,8 +45,12 @@ export function useExhibitionSheet(data, config = {}) {
     { key: 'name', label: 'sheet.field.name', value: 'name' },
     { key: 'aka', label: 'sheet.field.alsoKnownAs', value: 'alternate_name' },
     { key: 'location', label: 'sheet.field.location', value: (c) => [c.text.location, labelOf('countries', c.record.country_id)].filter(Boolean).join(', ') },
-    // A link to the partner's page, rendered by the wrapper's `museum` slot.
-    { key: 'museum', label: 'sheet.field.holdingMuseum', value: (c) => (partnerById.value.get(c.record.partner_id) ? c.record.partner_id : ''), render: 'custom' },
+    // The holding museum, rendered by the wrapper's `museum` slot: the item's
+    // holder text, then the partner it refers to (decision D3,
+    // inventory-app#2015). The value is the partner's id when the package
+    // carries the partner, otherwise the holder text, so the row stays for an
+    // item whose holder has no partner page.
+    { key: 'museum', label: 'sheet.field.holdingMuseum', value: (c) => (partnerById.value.get(c.record.partner_id) ? c.record.partner_id : (c.text.holder ?? '')), render: 'custom' },
     { key: 'originalOwner', label: 'sheet.field.originalOwner', value: 'initial_owner' },
     { key: 'currentOwner', label: 'sheet.field.currentOwner', value: 'owner' },
     { key: 'date', label: 'sheet.field.date', value: 'dates' },

package/src/dxa/gallery/useGallerySheet.js

@@ -45,8 +45,12 @@ export function useGallerySheet(data, config = {}) {
     { key: 'name', label: 'sheet.field.name', value: 'name' },
     { key: 'aka', label: 'sheet.field.alsoKnownAs', value: 'alternate_name' },
     { key: 'location', label: 'sheet.field.location', value: (c) => [c.text.location, labelOf('countries', c.record.country_id)].filter(Boolean).join(', ') },
-    // A link to the partner's page, rendered by the wrapper's `museum` slot.
-    { key: 'museum', label: 'sheet.field.holdingMuseum', value: (c) => (partnerById.value.get(c.record.partner_id) ? c.record.partner_id : ''), render: 'custom' },
+    // The holding museum, rendered by the wrapper's `museum` slot: the item's
+    // holder text, then the partner it refers to (decision D3,
+    // inventory-app#2015). The value is the partner's id when the package
+    // carries the partner, otherwise the holder text, so the row stays for an
+    // item whose holder has no partner page.
+    { key: 'museum', label: 'sheet.field.holdingMuseum', value: (c) => (partnerById.value.get(c.record.partner_id) ? c.record.partner_id : (c.text.holder ?? '')), render: 'custom' },
     { key: 'originalOwner', label: 'sheet.field.originalOwner', value: 'initial_owner' },
     { key: 'currentOwner', label: 'sheet.field.currentOwner', value: 'owner' },
     { key: 'date', label: 'sheet.field.date', value: 'dates' },

package/src/index.js

@@ -35,7 +35,7 @@ export {
   citation, relatedRecords, searchGlossary, timelineLinkFor, useGlossaryPopup, useRelatedRecords,
 } from './record/derivations.js'
 export { buildCollectionTree, collectionTreeFromThemes, useCollectionTree } from './record/collectionTree.js'
-export { groupByCountry, partnerHierarchy } from './record/partners.js'
+export { groupByCountry, partnerHierarchy, partnerView } from './record/partners.js'
 
 // Conventions every website had written for itself.
 export {

package/src/record/partners.js

@@ -10,6 +10,15 @@
 // nowhere: legacy nested an associated partner under the main partner it
 // belongs to, and the port flattened that into the country column instead.
 // `partnerHierarchy` is that relationship, read once.
+//
+// `partnerView` is what every rendering of one partner reads — a list line,
+// the summary under an item's holder, the partner page — built once here so
+// the contact block, the contact persons and the picture captions are read
+// the same way on every site. A partner is one type in every exporter family
+// (decision D4 of inventory-app#1699); what differs by family is only what
+// `ctx` carries.
+
+import { md as mdBlock, mdInline as mdInlineDefault, mdStrip as mdStripDefault } from '../i18n/markdown.js'
 
 /**
  * Whether `record` counts as a main (rather than associated) partner.
@@ -85,3 +94,136 @@ export function partnerHierarchy(partners) {
     roots,
   }
 }
+
+// ── One partner, for rendering ───────────────────────────────────────────────
+
+/**
+ * A partner's website or extra link, as an address a link can use. A value
+ * with no scheme (`www.example.org`, about a quarter of the packages' links)
+ * gets `https://` (decided 2026-09-25, inventory-app#2031); `http://` and
+ * `https://` are kept as they are. Any other scheme (`javascript:`, `data:`,
+ * `mailto:`) is not a website and yields `''`, so it never reaches an `href`.
+ * A port after a bare host (`host:8080`) is not a scheme.
+ */
+function websiteUrl(value) {
+  const url = String(value ?? '').trim()
+  if (!url) return ''
+  if (/^https?:\/\//i.test(url)) return url
+  if (url.startsWith('//')) return `https:${url}`
+  if (/^[a-z][a-z0-9+.-]*:(?!\d)/i.test(url)) return ''
+  return `https://${url}`
+}
+
+const byDisplayOrder = (a, b) => (a?.display_order ?? 0) - (b?.display_order ?? 0)
+
+/**
+ * The contact persons in legacy order (person 1 first), keeping only those
+ * with a name or a title — legacy printed a person block only then. Reads
+ * `contact_persons`; a package built before that list existed carries
+ * `contact_person_1`/`_2` instead (inventory-app#2007 removes them).
+ */
+function contactPersons(partner) {
+  const list = Array.isArray(partner?.contact_persons)
+    ? partner.contact_persons
+    : [partner?.contact_person_1, partner?.contact_person_2]
+  return list
+    .filter((person) => person && (person.name || person.title))
+    .map((person) => ({
+      title: person.title ?? '',
+      name: person.name ?? '',
+      phone: person.phone ?? '',
+      fax: person.fax ?? '',
+      email: person.email ?? '',
+    }))
+}
+
+/**
+ * The view-model of one partner: what viewer-layout's `PartnerPanel` renders
+ * in each of its variants, and what any other rendering of a partner reads.
+ *
+ * `partner` is a `partners.json` record; `text` its translation in the
+ * language shown (`{ name, description, city, address, phone, fax, email,
+ * website }`). `ctx` carries what differs by family, nothing else:
+ *
+ * - `countryLabel(countryId)` — the country's name;
+ * - `md`, `mdInline`, `mdStrip` — the renderers, when the site binds its
+ *   own (a glossary); the package's by default;
+ * - `route(partner)` — the partner's own page;
+ * - `objectsRoute(partner)` — the page of the items it holds;
+ * - `hidden(partner)` — a partner with no page of its own (the exhibitions'
+ *   rule): it keeps its name, and loses both links.
+ *
+ * Text is rendered once here: `name` and `description` are HTML (inline and
+ * block), `address` is block HTML; every other field is plain text.
+ */
+export function partnerView(partner, text = {}, ctx = {}) {
+  if (!partner) return null
+  const t = text ?? {}
+  const {
+    countryLabel = (id) => (id ?? ''),
+    md = mdBlock,
+    mdInline = mdInlineDefault,
+    mdStrip = mdStripDefault,
+    route = null,
+    objectsRoute = null,
+    hidden = null,
+  } = ctx
+
+  const source = String(t.name ?? partner.internal_name ?? partner.id)
+  const plainName = mdStrip(source)
+  const city = t.city ? String(t.city) : ''
+  const country = partner.country_id ? (countryLabel(partner.country_id) ?? '') : ''
+  const isHidden = hidden ? Boolean(hidden(partner)) : false
+  const itemCount = partner.item_count ?? 0
+  const website = websiteUrl(t.website)
+  const links = (partner.additional_urls ?? [])
+    .map((link) => ({ url: websiteUrl(link?.url), label: link?.title || link?.url || '' }))
+    .filter((link) => link.url)
+  const hasMap = Number.isFinite(partner.latitude) && Number.isFinite(partner.longitude)
+
+  const view = {
+    id: partner.id,
+    type: partner.type ?? '',
+    name: mdInline(source),
+    plainName,
+    city,
+    country,
+    location: [city, country].filter(Boolean).join(', '),
+    logos: [...(partner.logos ?? [])].sort(byDisplayOrder).map((logo) => ({
+      url: logo.url,
+      alt: logo.alt_text || plainName,
+      type: logo.logo_type ?? '',
+    })),
+    // A partner's pictures carry `alt_text`, not the per-language
+    // `captions` an item's images do: the alt text is the caption.
+    pictures: [...(partner.images ?? [])].sort(byDisplayOrder).map((picture) => ({
+      url: picture.url,
+      alt: picture.alt_text || plainName,
+      caption: picture.alt_text ?? '',
+      photographer: picture.photographer ?? '',
+      copyright: picture.copyright ?? '',
+    })),
+    description: md(t.description ?? ''),
+    contact: {
+      address: md(t.address ?? ''),
+      phone: t.phone ?? '',
+      fax: t.fax ?? '',
+      email: t.email ?? '',
+      website: website ? { url: website, label: String(t.website).trim() } : null,
+      links,
+    },
+    persons: contactPersons(partner),
+    map: hasMap
+      ? { latitude: partner.latitude, longitude: partner.longitude, zoom: partner.map_zoom ?? 15, label: plainName }
+      : null,
+    itemCount,
+    hidden: isHidden,
+    route: !isHidden && route ? (route(partner) ?? null) : null,
+    objectsRoute: !isHidden && itemCount && objectsRoute ? (objectsRoute(partner) ?? null) : null,
+  }
+  view.hasContact = Boolean(
+    view.contact.address || view.contact.phone || view.contact.fax || view.contact.email
+      || view.contact.website || view.contact.links.length || view.persons.length,
+  )
+  return view
+}