@museumwnf/viewer-core 1.16.1 → 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,13 +470,12 @@ 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
 
 | Export | Meaning |
 | --- | --- |
-| `projectName(key, t)` / `useProjectName()` / `PROJECT_ENTRIES` ⚠️ deprecated | a project's name by its legacy key (`ISL`, `EPM`, `DBA`, `BAR`, `AWE`, `DCA`, `DGA`, `EXTHE`, `GALLERIES`), through `core.project.*`; an unknown key reads as itself |
-| `projectFamily(key)` / `PROJECT_FAMILIES` ⚠️ deprecated | a project's colour family by the same legacy key (ISL and EPM share `ISLandEPM`, every exhibition shares `EXH`, …) — legacy's own class names, so a site's CSS reads as the stylesheet it was copied from; an unknown key reads as itself |
 | `useSection()` | the `meta.section` of the current route — see Routing |
 | `useFeaturedRecord(entity, { withImage = true, seed })` | one record at random for a landing page's spotlight, among those with an image; null until the entity is loaded; `seed` pins the pick |
 | `sectionMeta(chrome = [])` | returns `meta(section, ...entities) => ({ section, entities: [...chrome, ...entities] })` — a route's `meta` in one call, `chrome` being the entities every page of the site loads regardless of which one it is |
@@ -461,26 +483,24 @@ under the main partner it belongs to.
 
 #### Projects, from the data package (epic metanull/inventory-app#1727)
 
-`manifest.projects` — a project UUID → `{ name: { <lang>: '…' }, site_url, related_database_url, artistic_introduction_url }` map, emitted by every exporter since #1727 phase 2 — is project data moved out of viewer-core and into the data package a project's own exporter writes. It is additive: a package built before phase 2 simply has no `projects` key, and every function below reads that exactly like an unknown project id — `null`, never a throw.
+`manifest.projects` — a project UUID → `{ name: { <lang>: '…' }, site_url, related_database_url, artistic_introduction_url }` map, emitted by every exporter since #1727 phase 2 — is project data read from the data package a project's own exporter writes, not carried in viewer-core. It is additive: a package built before phase 2 simply has no `projects` key, and every function below reads that exactly like an unknown project id — `null`, never a throw.
 
 | Export | Meaning |
 | --- | --- |
 | `projectLabel(manifest, projectId, lang)` | `manifest.projects[projectId].name[…]`, with the same language fallback every translated field in this package follows (`resolveRecordLanguage`): `lang`, then this package's base language (`en`), then the entry's first carried language. `null` when the package has no `projects` section, `projectId` isn't a key of it, or the entry names nothing. |
 | `projectLinks(manifest, projectId)` | `{ siteUrl, relatedDatabaseUrl, artisticIntroductionUrl }` from the same entry (camelCased, individually nullable — a project may simply have no value for one). `null` for the whole result when the package predates the section or doesn't carry `projectId`. |
-| `useProjects()` | `{ label(projectId, lang?), links(projectId) }` bound to the installed data package and active language — the manifest-driven analogue of `useProjectName()`. |
+| `useProjects()` | `{ label(projectId, lang?), links(projectId) }` bound to the installed data package and active language. |
 
-Migration mapping, from the epic's design comment (§B) — what each of the five usages moves to:
+What each of the sites' former legacy-key usages reads now, from `manifest.projects` (see CHANGELOG.md 2.0.0 for the full removal/migration notes):
 
-| Today (deprecated) | Reads from `manifest.projects` instead |
+| Formerly | Now reads |
 | --- | --- |
-| RecordView citation line (`projectName(record.project_key, t)`) | `projectLabel(manifest, record.project_id, lang)` / `useProjects().label(record.project_id)` — tracked on viewer-layout#81 |
-| ItemSheet "Source database" line + `mwnf-chip--<family>` colour | same `projectLabel`, plus a site-config map from project UUID to a CSS token (no more `projectFamily`) |
+| RecordView citation line (`projectName(record.project_key, t)`) | `projectLabel(manifest, record.project_id, lang)` / `useProjects().label(record.project_id)` |
+| ItemSheet "Source database" line + `mwnf-chip--<family>` colour | `projectLabel`, plus a site-config map from project UUID to a CSS token |
 | "Search related database" block | `projectLinks(manifest, projectId).relatedDatabaseUrl`, rendered iff non-null |
 | Artistic Introduction link | `projectLinks(manifest, projectId).artisticIntroductionUrl`, iff non-null |
-| Search-scope include-EPM checkbox | unchanged by this phase — stays the site's own `dataset.config.js` scope list (epic decision 5) |
-| Partner Museums/Institutions split | unchanged by this phase — `partner.project_uuids` matched against a site-config list (epic decision 5) |
-
-`PROJECT_ENTRIES`, `PROJECT_FAMILIES` and `projectFamily` are deprecated as of this phase and will be removed in the cleanup wave once every site has migrated (phase 4); `projectName()`/`useProjectName()` are unaffected for now — they still resolve a *legacy key* through the installed texts for whatever hasn't migrated yet.
+| Search-scope include-EPM checkbox | the site's own `dataset.config.js` scope list (epic decision 5) |
+| Partner Museums/Institutions split | `partner.project_uuids` matched against a site-config list (epic decision 5) |
 
 ### `@museumwnf/viewer-core/legacy`
 
@@ -498,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
@@ -728,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'
@@ -751,7 +776,8 @@ describe('smoke test', () => {
     app.unmount()
   })
 })
-\\\
+```
+
 ## Licence
 
 This package is Content of the MWNF Website under the [MWNF legal
@@ -763,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": "1.16.1",
+  "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/conventions.js

@@ -7,88 +7,11 @@ import { resolveRecordLanguage } from './composables/useRecordLanguage.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.
-//
-// @deprecated Project data belongs in the data package, not in viewer-core.
-// Read a project's name from `manifest.projects` via `projectLabel()` /
-// `useProjects()` instead (epic metanull/inventory-app#1727, phase 3) — see
-// the migration table below. Kept only for sites that have not migrated yet
-// (phase 4); removed in the cleanup wave.
-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.
-//
-// @deprecated Chip colour is a per-project site-config map keyed by the
-// project UUID (epic #1727 decision 1: no family/parent relation is modeled
-// anywhere, this table was always a frontend invention). Removed in the
-// cleanup wave alongside `PROJECT_ENTRIES`.
-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.
- *
- * @deprecated See `PROJECT_FAMILIES`.
- */
-export function projectFamily(key) {
-  return PROJECT_FAMILIES[key] ?? (key ?? '')
-}
-
 // ── Projects, from the data package ─────────────────────────────────────────
 //
-// `manifest.projects` (epic metanull/inventory-app#1727, phase 2 —
-// `scripts/exporters`) is what `PROJECT_ENTRIES`/`PROJECT_FAMILIES` above
-// should have been: project data belongs in the data package a project's own
-// exporter writes, not in a table viewer-core carries for every website. Its
-// shape, one entry per project UUID:
+// `manifest.projects` (epic metanull/inventory-app#1727 — `scripts/exporters`)
+// is project data from the data package a project's own exporter writes.
+// Its shape, one entry per project UUID:
 //
 //   manifest.projects[projectId] = {
 //     name: { <lang>: '…' },                    // per-language title
@@ -99,21 +22,8 @@ export function projectFamily(key) {
 //
 // A data package built before this phase simply has no `projects` key at
 // all; `projectLabel`/`projectLinks` answer `null` for that case exactly as
-// they do for an unknown `projectId` — a site notices nothing until it
-// migrates. Migration mapping, from the epic's design comment (§B):
-//
-//   RecordView citation line           → projectLabel(manifest, record.project_id, lang) (viewer-layout#81)
-//   ItemSheet "Source database" line   → same, plus a site-config colour map keyed by project UUID (no more `projectFamily`)
-//   "Search related database" block    → projectLinks(manifest, id).relatedDatabaseUrl, rendered iff non-null
-//   Artistic Introduction link         → projectLinks(manifest, id).artisticIntroductionUrl, iff non-null
-//   search-scope include-EPM checkbox  → stays the site's own dataset.config.js scope list (not modeled here — decision 5)
-//   partner Museums/Institutions split → partner.project_uuids matched against a site-config list (decision 5)
-//
-// `PROJECT_ENTRIES`, `PROJECT_FAMILIES` and `projectFamily` are deprecated by
-// this section and removed in the cleanup wave once every site has moved
-// (phase 4). `projectName()`/`useProjectName()` are unaffected — they still
-// resolve a *legacy key* through the installed texts, for whatever has not
-// migrated yet.
+// they do for an unknown `projectId`. See CHANGELOG.md 2.0.0 for the
+// migration notes from this package's former legacy-key conventions.
 
 /** One entry of `manifest.projects`, or `null` when the package predates
  * the section or does not carry `projectId`. */
@@ -156,9 +66,8 @@ export function projectLinks(manifest, projectId) {
 
 /**
  * `projectLabel`/`projectLinks` bound to the installed data package and
- * texts, for a component — the manifest-driven analogue of
- * `useProjectName()`. `label(projectId)` reads the site's active language;
- * pass a language explicitly to read another.
+ * texts, for a component. `label(projectId)` reads the site's active
+ * language; pass a language explicitly to read another.
  */
 export function useProjects() {
   const { manifest } = useDataPackage()

package/src/dxa/exhibition/useExhibitionData.js

@@ -168,9 +168,8 @@ export function useExhibitionData(config = {}) {
   // A member is borrowed from the MWNF project that originally published
   // it. The name is the data package's own `manifest.projects` entry
   // (populated by the importer/exporter), keyed by this record's
-  // `project_id` (a UUID) — not viewer-core's deprecated, legacy-key-keyed
-  // `projectName()`/`projectFamily()`, and not an exhibition's own
-  // project-key comparisons either. The manifest already names an
+  // `project_id` (a UUID) — not a legacy-key lookup, and not an exhibition's
+  // own project-key comparisons either. The manifest already names an
   // exhibition's own native project under its own uuid (the sibling
   // `Collection` the importer creates alongside every `Project` carries the
   // same title), so there is no special case here for a native member any

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,12 +35,11 @@ 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 {
-  PROJECT_ENTRIES, PROJECT_FAMILIES, mwnfLinks, projectFamily, projectLabel,
-  projectLinks, projectName, sectionMeta, useFeaturedRecord, useProjectName,
+  mwnfLinks, projectLabel, projectLinks, sectionMeta, useFeaturedRecord,
   useProjects, useSection,
 } from './conventions.js'
 

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
+}