@museumwnf/viewer-core 2.0.0 → 2.2.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,14 @@ 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 (the legacy `contact_person_1`/`_2` pair is not read). 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 |
 | --- | --- |
 | `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 |
+| `useFeaturedRecord(entity, { withImage = true, seed, filter })` | 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; `filter(record)` applies a site's own visible rule first |
 | `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 |
 | `mwnfLinks` | the portal and sibling-site addresses the four DXA configs each repeat under `links` — frozen, spread into a site's own `links` rather than retyped |
 
@@ -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
@@ -609,6 +638,49 @@ export const { tr, md, mdInline, mdStrip, labelOf, loadEnglish } = catalogue
 | `index(name, key = 'id')` | a `Map` of `entity(name)`'s records by `key` — the visible ones, unlike `byId` |
 | `availableLanguages`, `loadTranslations`, `translations` | the package's own, re-exported so a site reads everything through the one object |
 
+### The catalogue data layer
+
+`useCatalogue` is `useCatalogueData` plus what a catalogue site — a
+standalone product, or a new product scaffolded from `website-template` —
+otherwise re-types for itself: the catalogue entities, their lookups, the
+labels, the routes and the one result row. A site calls it once, in its
+`data.js`, and keeps next to it only what is its own (a scope rule, a
+collection tree, its legacy address mappings).
+
+```js
+import { useCatalogue } from '@museumwnf/viewer-core'
+
+export const data = useCatalogue({
+  eager: ['items', 'countries', 'partners', 'dynasties', 'glossary'],
+  visible: { items: (item) => item.display_status !== 'N' },
+})
+data.loadEnglish()
+
+export const { items, itemRow, countryLabel, tr, md, mdInline } = data
+```
+
+| Export | Meaning |
+| --- | --- |
+| `useCatalogue(options)` | `useCatalogueData(options)`'s own return, plus: `items`, `countries`, `partners`, `dynasties` (the visible records, `null` until loaded); `itemById` (every item, the visible rule not applied — for a page that deliberately shows a hidden one), `partnerById`, `countryById`, `dynastyById`; `itemLabel(item)`, `countryLabel(id)`, `partnerLabel(id)`, `dynastyLabel(id)` (plain text, `''` for nothing); `itemRoute(item)`, `partnerRoute(partner)` (the `item`/`partner` routes by name); `itemRow(item, meta = ['country', 'dates'])` — the row `RecordList`/`RecordGrid`/`RelatedRecords` share, `meta` naming what follows the name in order: `'country'`, `'dates'`, `'location'`, `'dynasties'`, `'holder'` (the partner, only when the package carries it), or a function `(item, text) => string` |
+| `CATALOGUE_PAGE_SIZE`, `CATALOGUE_DATE_MODE` | `20` and `'overlap'`: the standalone pages' size and date rule (decision D5) — named apart from `/dxa`'s `PAGE_SIZE`/`DATE_MODE` (`9`, `'contain'`), which a DXA site imports next to this root |
+| `objectsAndMonumentsSummary({ matching, t })` | legacy's "[N objects, M monuments]", a results spec's `summary` |
+
+The field search of the legacy `database.php` form — keyword rows each
+naming a field, folded with AND/OR — around `useKeywordIndex`'s `fields`
+grammar:
+
+| Export | Meaning |
+| --- | --- |
+| `searchFields({ dynastyLabel })` | the haystack of each field, as legacy's form searched it: `keyword`, `name`, `location`, `provenance`, `patron`, `artist`, `material`, `other`, and `dynasty` when a `dynastyLabel` is given |
+| `searchFieldOptions(fields)` | `[{ key, label }]` (entry names), in legacy's order, for the fields `fields` carries — `SearchFormView`'s `fields` |
+| `useSearchFieldOptions(fields)`, `searchFieldLabel(key, t)` | the same resolved, `[{ value, label }]`, for a select a site draws itself; one field's label |
+| `searchRows(filters, count = 4)`, `searchRowKeys(count = 4)` | the keyword rows the query carries (`q`/`field`, then `qN`/`fieldN`/`opN`), and their query keys for a results spec's `keys` |
+| `searchedFor(filters, t, { rows, extras })`, `searchSummary(ctx, options)` | the "Name: "bowl" · OR Location: "Cairo" · From 900 · Language: FR" line — `extras`, `(filters, t) => string`, append a site's own parts — and the results summary built on it (what was searched, or all items; then the count) |
+| `useFieldSearch({ fields, entity = 'items', rows = 4, rank = 'hits', expand })` | one long-lived index (the glossary and country expansions by default), its search language following the query's `lang`; `narrow(list, filters)` is a results spec's `narrow` — the matches in rank order, kept to the scoped `list`. Pass `sort: false` to the spec. |
+
+`useFeaturedRecord(entity, { filter })` narrows the candidates by a site's
+own visible rule first: it reads the raw entity.
+
 ### Routing
 
 The convention, applied by the router every website shares:
@@ -724,12 +796,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 +819,8 @@ describe('smoke test', () => {
     app.unmount()
   })
 })
-\\\
+```
+
 ## Licence
 
 This package is Content of the MWNF Website under the [MWNF legal
@@ -759,5 +832,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.2.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

@@ -0,0 +1,128 @@
+import { useCatalogueData } from '../composables/useCatalogueData.js'
+import { byId } from '../composables/useEntities.js'
+
+// The catalogue data layer: what a website built on the generic entries —
+// the standalone products, and every new product scaffolded from
+// `website-template` — re-typed around `useCatalogueData` for itself, three
+// times (inventory-app#2037): the entity refs and lookups a catalogue reads,
+// the label and route helpers, the one result row every list shows, the
+// "[N objects, M monuments]" count. A site keeps one instance of it, in its
+// `data.js`, next to what is genuinely its own (a scope rule, a collection
+// tree, its legacy address mappings).
+//
+// The DXA families have their own layer (`@museumwnf/viewer-core/dxa`), over
+// the same `useCatalogueData`; nothing here reads it.
+
+/** Twenty rows a page: the legacy standalone pages' own size. */
+export const CATALOGUE_PAGE_SIZE = 20
+
+/**
+ * The standalone date rule (decision D5): a record overlapping the window
+ * counts, a record with one date is tolerated. The DXA families contain
+ * (`@museumwnf/viewer-core/dxa`'s `DATE_MODE`); a site names its rule once.
+ */
+export const CATALOGUE_DATE_MODE = 'overlap'
+
+/**
+ * The website's catalogue: everything `useCatalogueData` returns, plus the
+ * catalogue entities, their lookups, the labels, the routes and the result
+ * row. Takes `useCatalogueData`'s own options (`eager`, `defaultLanguage`,
+ * `visible`, `glossary`); called once, at the top of the site's `data.js`.
+ *
+ * - `items`, `countries`, `partners`, `dynasties`: the visible records
+ *   (`visible` applies), `null` until loaded.
+ * - `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.
+ * - `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`.
+ */
+export function useCatalogue(options = {}) {
+  const data = useCatalogueData(options)
+  const { tr, labelOf, mdInline } = data
+
+  const items = data.entity('items')
+  const countries = data.entity('countries')
+  const partners = data.entity('partners')
+  const dynasties = data.entity('dynasties')
+
+  const itemById = byId('items')
+  const partnerById = data.index('partners')
+  const countryById = data.index('countries')
+  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 itemRoute = (item) => ({ name: 'item', params: { id: item.id } })
+  const partnerRoute = (partner) => ({ name: 'partner', params: { id: partner.id } })
+
+  const META = {
+    country: (item) => countryLabel(item.country_id),
+    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) : ''),
+  }
+
+  function itemRow(item, meta = ['country', 'dates']) {
+    const text = tr('items', item.id)
+    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)))
+        .filter(Boolean),
+      badge: item.type ?? '',
+      to: itemRoute(item),
+    }
+  }
+
+  return {
+    ...data,
+    items,
+    countries,
+    partners,
+    dynasties,
+    itemById,
+    partnerById,
+    countryById,
+    dynastyById,
+    itemLabel,
+    countryLabel,
+    partnerLabel,
+    dynastyLabel,
+    itemRoute,
+    partnerRoute,
+    itemRow,
+  }
+}
+
+/**
+ * Legacy's count, "[N objects, M monuments]", over what matched: a results
+ * spec's `summary`. A monument is a record of type `monument`; everything
+ * else counts as an object.
+ */
+export function objectsAndMonumentsSummary({ matching, t }) {
+  let objects = 0
+  let monuments = 0
+  for (const item of matching ?? []) {
+    if (item.type === 'monument') monuments++
+    else objects++
+  }
+  return [
+    { label: t('catalogue.results.objectsFound'), count: objects },
+    { label: t('catalogue.results.monumentsFound'), count: monuments },
+  ]
+}

package/src/catalogue/fieldSearch.js

@@ -0,0 +1,176 @@
+import { computed, ref } from 'vue'
+import { useI18n } from '../i18n/index.js'
+import { combineExpansions, countryExpansion, glossaryExpansion, useKeywordIndex } from './keywordIndex.js'
+
+// The field search of the legacy `database.php` form — keyword rows, each
+// naming a field, folded with AND/OR — which the three standalone products
+// each wired for themselves (inventory-app#2037): the fields' haystacks, the
+// field options and their labels, the rows the query string carries, the
+// "searched for" line, the index. `useKeywordIndex`'s `fields` grammar is
+// the engine; this is the rest of the machinery around it, written once.
+
+/**
+ * What each field of the form searches, field for field as legacy's form
+ * did. `text` is the record's translation in the search language, English
+ * behind it. `keyword` and `location` also carry the record's `country_id`:
+ * `countryExpansion` turns a typed country name into its id, and a field is
+ * only found by that expansion if its haystack carries the id.
+ *
+ * `dynastyLabel(id)` turns on the `dynasty` field — Islamic Art's form has
+ * it, Baroque Art's and Sharing History's do not.
+ */
+export function searchFields({ dynastyLabel } = {}) {
+  const fields = {
+    keyword: (item, text) => [
+      text.name ?? item.internal_name, text.alternate_name, text.description, item.country_id, ...(item.tags ?? []),
+    ],
+    name: (item, text) => text.name ?? item.internal_name,
+    location: (item, text) => [text.location, item.country_id],
+    provenance: (item, text) => text.provenance,
+    patron: (item, text) => text.patrons ?? text.initial_owner,
+    artist: (item, text) => [...(item.artist_names ?? []), text.architects],
+    material: (item, text) => text.type,
+    // The catch-all across the descriptive fields the others leave out.
+    other: (item, text) => [
+      text.description, text.method_for_datation, text.method_for_provenance, text.obtention,
+      text.bibliography, text.workshop, text.scriber, text.binding_desc, text.history,
+    ],
+  }
+  if (dynastyLabel) fields.dynasty = (item) => (item.dynasty_ids ?? []).map(dynastyLabel)
+  return fields
+}
+
+// Every field of the form, in legacy's order, with its entry name.
+const FIELD_OPTIONS = [
+  { key: 'keyword', label: 'catalogue.field.keywords' },
+  { key: 'name', label: 'sheet.field.name' },
+  { key: 'location', label: 'sheet.field.location' },
+  { key: 'provenance', label: 'sheet.field.provenance' },
+  { key: 'dynasty', label: 'catalogue.facet.periodDynasty' },
+  { key: 'patron', label: 'catalogue.field.patron' },
+  { key: 'artist', label: 'catalogue.field.artist' },
+  { key: 'material', label: 'catalogue.field.material' },
+  { key: 'other', label: 'catalogue.field.other' },
+]
+
+/**
+ * The options of the form's field select — `[{ key, label }]`, `label` an
+ * entry name, in legacy's order — for the fields `fields` carries: what
+ * `SearchFormView`'s `fields` takes.
+ */
+export function searchFieldOptions(fields) {
+  return FIELD_OPTIONS.filter((option) => option.key in fields)
+}
+
+/** One field's label, resolved: `key` is what the query string carries. */
+export function searchFieldLabel(key, t) {
+  switch (key) {
+    case 'keyword': return t('catalogue.field.keywords')
+    case 'name': return t('sheet.field.name')
+    case 'location': return t('sheet.field.location')
+    case 'provenance': return t('sheet.field.provenance')
+    case 'dynasty': return t('catalogue.facet.periodDynasty')
+    case 'patron': return t('catalogue.field.patron')
+    case 'artist': return t('catalogue.field.artist')
+    case 'material': return t('catalogue.field.material')
+    case 'other': return t('catalogue.field.other')
+    default: return key
+  }
+}
+
+/**
+ * The same options resolved, `[{ value, label }]`, for a select a site draws
+ * itself — the results page's refine row.
+ */
+export function useSearchFieldOptions(fields) {
+  const { t } = useI18n()
+  return computed(() => searchFieldOptions(fields).map((option) => ({ value: option.key, label: searchFieldLabel(option.key, t) })))
+}
+
+/**
+ * The keyword rows the query string carries: `q`/`field` for the first
+ * (`SearchFormView`'s own, unnumbered), `qN`/`fieldN`/`opN` for the next —
+ * three from the entrance, a fourth for the results page's refine row.
+ * A row with no field searches `keyword`; with no operator, AND.
+ */
+export function searchRows(filters, count = 4) {
+  const rows = []
+  for (let n = 1; n <= count; n++) {
+    rows.push({
+      keyword: n === 1 ? filters.q : filters[`q${n}`],
+      field: (n === 1 ? filters.field : filters[`field${n}`]) || 'keyword',
+      cond: n === 1 ? 'AND' : filters[`op${n}`] || 'AND',
+    })
+  }
+  return rows
+}
+
+/** The query keys `searchRows` reads, for a results spec's `keys`. */
+export function searchRowKeys(count = 4) {
+  const keys = ['q', 'field']
+  for (let n = 2; n <= count; n++) keys.push(`q${n}`, `field${n}`, `op${n}`)
+  return keys
+}
+
+/**
+ * What was searched, spelled out: `Name: "bowl"`, `AND Location: "Cairo"`,
+ * the years, the search language, then the site's own `extras` —
+ * `(filters, t) => string` each, an empty string for nothing. Legacy's
+ * recap line, never just a count, so a visitor who scrolls past the form
+ * still reads what for.
+ */
+export function searchedFor(filters, t, { rows = 4, extras = [] } = {}) {
+  const parts = searchRows(filters, rows)
+    .filter((row) => row.keyword)
+    .map((row, i) => `${i > 0 ? `${row.cond} ` : ''}${searchFieldLabel(row.field, t)}: "${row.keyword}"`)
+  if (filters.from) parts.push(`${t('catalogue.filter.from')} ${filters.from}`)
+  if (filters.to) parts.push(`${t('catalogue.filter.to')} ${filters.to}`)
+  if (filters.lang) parts.push(`${t('catalogue.search.language')}: ${String(filters.lang).toUpperCase()}`)
+  for (const extra of extras) {
+    const part = extra(filters, t)
+    if (part) parts.push(part)
+  }
+  return parts
+}
+
+/**
+ * The results page's summary: what was searched (`searchedFor`), or "all
+ * items" for an empty query, then the count. `options` is `searchedFor`'s.
+ */
+export function searchSummary({ filters, t, pageInfo }, options = {}) {
+  const parts = searchedFor(filters, t, options)
+  return [
+    { label: t('catalogue.search.summary'), value: parts.length ? parts.join(' · ') : t('catalogue.results.allItems') },
+    { label: t('catalogue.results.itemsFound'), count: pageInfo.total },
+  ]
+}
+
+/**
+ * The index behind the results page: one long-lived `useKeywordIndex` over
+ * `entity` (`fields` grammar, legacy's `rank: 'hits'` order, the glossary
+ * and country expansions of `database_results.php`), its search language
+ * kept in step with the query's `lang`. `narrow(list, filters)` is a results
+ * spec's `narrow`: the matches in rank order, kept to what `list` (the
+ * records the spec's `scope` let through) carries. Pass `sort: false` to the
+ * spec, so the rank order stands.
+ */
+export function useFieldSearch({
+  fields,
+  entity = 'items',
+  rows = 4,
+  rank = 'hits',
+  expand = combineExpansions(glossaryExpansion(), countryExpansion()),
+} = {}) {
+  const language = ref('')
+  const index = useKeywordIndex(entity, { grammar: 'fields', fields, language, rank, expand })
+
+  function narrow(list, filters) {
+    language.value = filters.lang || ''
+    const matches = index.search(searchRows(filters, rows))
+    if (!list) return matches
+    const allowed = new Set(list.map((record) => record.id))
+    return matches.filter((record) => allowed.has(record.id))
+  }
+
+  return { narrow, index }
+}

package/src/conventions.js

@@ -108,13 +108,16 @@ function seeded(seed) {
  * 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.
+ * deterministic. `filter(record)` narrows the candidates first — the site's
+ * own visible rule, since this reads the raw entity (Sharing History's
+ * hidden illustrations, `display_status: 'N'`, must never be picked).
  */
-export function useFeaturedRecord(entity, { withImage = true, seed, images = 'images' } = {}) {
+export function useFeaturedRecord(entity, { withImage = true, seed, images = 'images', filter } = {}) {
   const records = entityRef(entity)
   const random = seed == null ? Math.random : seeded(seed)
   return computed(() => {
-    const all = toValue(records) ?? []
+    const loaded = toValue(records)
+    const all = filter ? (loaded ?? []).filter(filter) : loaded ?? []
     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

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

@@ -1,6 +1,13 @@
 export { createViewer } from './createViewer.js'
 export { createStandardViewer } from './createStandardViewer.js'
 export { useCatalogueData } from './composables/useCatalogueData.js'
+export {
+  CATALOGUE_DATE_MODE, CATALOGUE_PAGE_SIZE, objectsAndMonumentsSummary, useCatalogue,
+} from './catalogue/catalogue.js'
+export {
+  searchFieldLabel, searchFieldOptions, searchFields, searchRowKeys, searchRows, searchSummary, searchedFor,
+  useFieldSearch, useSearchFieldOptions,
+} from './catalogue/fieldSearch.js'
 export { useDataPackage } from './composables/useDataPackage.js'
 export { byId, entityRef, loadEntities, useEntities } from './composables/useEntities.js'
 export { resolveRecordLanguage, useRecordLanguage } from './composables/useRecordLanguage.js'
@@ -35,7 +42,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,132 @@ 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.
+ */
+function contactPersons(partner) {
+  const list = Array.isArray(partner?.contact_persons) ? partner.contact_persons : []
+  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
+}