@museumwnf/viewer-core 1.15.1 → 1.16.1

package/src/dxa/exhibition/useExhibitionPartner.js

@@ -0,0 +1,62 @@
+// The partner list and profile, as specs. The grouping, the A–Z toggle, the
+// tab strip's mechanics, the language switch and the media gallery are the
+// platform's (`PartnerListView`/`RecordView`); what stays here is an
+// exhibition's own — the E6 hidden-partner rule (the view reads the raw
+// `partners` entity directly, not `visiblePartners`, so it never sees that
+// filter unless told), the country label, and which route a museum or an
+// institution goes to. This exhibition-shaped `partnerSpecs.js` never
+// carried an objects-page spec (no `PartnerObjects.vue` counterpart built
+// on it), unlike the gallery family's `partner.js`.
+
+/**
+ * The exhibition's partner specs, over its data layer's `data`.
+ *
+ * Reads `data.defaultLang`, `data.isHiddenPartner`, `data.labelOf`,
+ * `data.partnerRoute`. `config` carries nothing today.
+ */
+export function useExhibitionPartner(data, config = {}) {
+  void config
+  const { defaultLang, isHiddenPartner, labelOf, partnerRoute } = data
+
+  // ── The list (Partners.vue) ─────────────────────────────────────────
+  //
+  // The DXA shape: no tier column at all — legacy's museum/institution
+  // split is a route, not a group here — an A–Z / Z–A toggle over the
+  // country groups, and every partner gets a row whether or not it holds
+  // anything (legacy's MWNF-384 branch). `variant: 'open'` keeps every
+  // group expanded, as legacy's page did with no accordion at all.
+  const partnerListSpec = {
+    scope: (partner) => !isHiddenPartner(partner),
+    group: { tier: false, order: 'country' },
+    variant: 'open',
+    orderToggle: true,
+    label: (countryId) => labelOf('countries', countryId),
+    route: (partner) => partnerRoute(partner),
+  }
+
+  // ── The profile (PartnerProfile.vue) ─────────────────────────────────
+  //
+  // No `fields`: legacy's Description/Contact/Logo tabs are three different
+  // shapes (Markdown, an address block, a bare image), not three rows of
+  // one sheet, so the panel is built in the view's slots over
+  // `text`/`record` directly rather than forced through `sheetRows`. No
+  // `citation`/`related` either — legacy's partner page has neither.
+  const partnerSheetSpec = {
+    entity: 'partners',
+    route: (partner) => partnerRoute(partner),
+    citation: false,
+    related: false,
+    media: (record, { language }) =>
+      [...(record.images ?? [])]
+        .sort((a, b) => (a.display_order ?? 0) - (b.display_order ?? 0))
+        .map((p) => ({
+          url: p.url,
+          alt: labelOf('partners', record.id),
+          caption: p.captions?.[language] ?? p.captions?.[defaultLang] ?? '',
+          photographer: p.photographer ?? '',
+          copyright: p.copyright ?? '',
+        })),
+  }
+
+  return { partnerListSpec, partnerSheetSpec }
+}

package/src/dxa/exhibition/useExhibitionSheet.js

@@ -0,0 +1,126 @@
+// The item sheet, as a spec: what viewer-layout's `RecordView` renders on
+// `/item/:id`. The mechanics — which language the record is read in, what
+// is loaded for it, the glossary terms it reaches, how a field becomes a
+// row, the credits, the citation, the related records — are the platform's.
+// What is declared here is only what is an exhibition's: the field
+// specification (legacy DatabaseItem.vue's `objectData`, field for field),
+// the photos in their order, the related tile, and the citation whose
+// project name follows an exhibition's own rule. Every label is an entry
+// name, written out so the check that every name resolves can read it.
+//
+// Order and labels are the legacy sheet's. Empty values are dropped by the
+// engine, as legacy's `filterData` did. `notice` and `notice_c` were never
+// imported; `notice_b` is the image rights statement, imported as
+// `extra.copyright` and rendered as the last row, where legacy put its own
+// block. The labels are in the language the visitor reads the website in —
+// where it differs from the record's (a deep link into a borrowed record in
+// a language an exhibition does not offer) they fall back to English,
+// which is where legacy pinned them anyway.
+//
+// Legacy shows both descriptions when both exist, with the short one
+// collapsed behind a toggle (the view's, folded after the description);
+// when only one exists it is relabelled plain "Description". EPM records
+// are the common case of the latter.
+
+/**
+ * The exhibition's item-sheet spec, over its data layer's `data`.
+ *
+ * Reads `data.defaultLang`, `data.itemRoute`, `data.labelOf`,
+ * `data.mdInline`, `data.mdStrip`, `data.partnerById`, `data.projectName`,
+ * `data.tr`, `data.translations`. `config` carries nothing today.
+ */
+export function useExhibitionSheet(data, config = {}) {
+  void config
+  const { defaultLang, itemRoute, labelOf, mdInline, mdStrip, partnerById, projectName, tr, translations } = data
+
+  const bothDescriptions = (c) => Boolean(c.text.description) && Boolean(c.text.short_description)
+
+  const dynastyNames = (c) =>
+    (c.record.dynasty_ids ?? [])
+      .map((id) => translations('dynasties', c.language)[id]?.name ?? translations('dynasties', defaultLang)[id]?.name ?? '')
+      .filter(Boolean)
+      .join(', ')
+
+  const fields = [
+    { 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' },
+    { 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' },
+    { key: 'artist', label: 'sheet.field.artists', value: (c) => c.record.artist_names, join: ', ' },
+    { key: 'scribe', label: 'sheet.field.scribe', value: 'scriber' },
+    { key: 'workshop', label: 'sheet.field.workshop', value: 'workshop' },
+    { key: 'type', label: 'sheet.field.type', value: 'type' },
+    { key: 'inventoryNumber', label: 'sheet.field.inventoryNumber', value: (c) => c.record.owner_reference },
+    { key: 'materials', label: 'sheet.field.materials', value: (c) => c.text.materials, join: '; ' },
+    { key: 'dimensions', label: 'sheet.field.dimensions', value: 'dimensions' },
+    { key: 'dynasty', label: 'sheet.field.periodDynasty', value: dynastyNames },
+    { key: 'production', label: 'sheet.field.placeOfProduction', value: 'place_of_production' },
+    { key: 'provenance', label: 'sheet.field.provenance', value: 'provenance' },
+    { key: 'binding', label: 'sheet.field.binding', value: 'binding_desc' },
+    { key: 'description', label: 'sheet.field.description', value: 'description', render: 'block' },
+    // The only description there is, under the plain label; the toggled one
+    // is the view's, folded after `description` when both exist.
+    { key: 'shortDescription', label: 'sheet.field.description', value: 'short_description', render: 'block', when: (c) => !bothDescriptions(c) },
+    { key: 'catalogue', label: 'sheet.field.catalogueLink', value: 'linkcatalogs', render: 'link' },
+    { key: 'obtention', label: 'sheet.field.obtentionMethod', value: 'obtention' },
+    { key: 'datation', label: 'sheet.field.datationMethod', value: 'method_for_datation' },
+    { key: 'provenanceMethod', label: 'sheet.field.provenanceMethod', value: 'method_for_provenance' },
+    { key: 'bibliography', label: 'sheet.field.bibliography', value: 'bibliography', render: 'block' },
+    { key: 'copyright', label: 'sheet.field.copyrightInformation', value: 'copyright' },
+  ]
+
+  const itemSheet = {
+    entity: 'items',
+    translations: ['glossary', 'dynasties', 'partners'],
+    // Attribution names are language-independent, but the importer files
+    // `author` / `copy_editor` for EPM records on the Arabic row only (a
+    // known gap, recorded in the exporter's README). Legacy printed them on
+    // every sheet, so the platform reads them off another row when the
+    // active one has neither — the one place a page reads across
+    // languages, and only for proper names.
+    attribution: ['author', 'copy_editor'],
+    fields,
+    layout: 'list',
+    shortDescription: 'short_description',
+    shortDescriptionAfter: 'description',
+    media: (record, { language }) =>
+      [...(record.images ?? [])]
+        .sort((a, b) => (a.display_order ?? 0) - (b.display_order ?? 0))
+        .map((p) => ({
+          url: p.url,
+          alt: labelOf('items', record.id),
+          caption: p.captions?.[language] ?? p.captions?.[defaultLang] ?? '',
+          photographer: p.photographer ?? '',
+          copyright: p.copyright ?? '',
+        })),
+    citation: {
+      permalink: false,
+      heading: 'record.citation.ofThisPage',
+      // The manifest's own project name for this record, read in the
+      // record's own display language, not the site's active one — a
+      // record legacy left nameless (the Explore monuments database) still
+      // cites nothing.
+      project: (record, { language }) => projectName(record, language),
+    },
+    related: {
+      variant: 'grid',
+      heading: 'exhibition.related.objects',
+      actionLabel: 'exhibition.action.seeDatabaseEntry',
+      record: ({ record: other, justification }) => ({
+        id: other.id,
+        image: other.images?.[0]?.url ?? '',
+        imageAlt: labelOf('items', other.id),
+        name: mdInline(tr('items', other.id, defaultLang).name ?? other.internal_name ?? ''),
+        meta: [labelOf('countries', other.country_id), justification ? mdStrip(justification) : ''].filter(Boolean),
+        to: itemRoute(other),
+      }),
+    },
+    route: 'item',
+  }
+
+  return { itemSheet }
+}

package/src/dxa/exhibition/useExhibitionTimeline.js

@@ -0,0 +1,310 @@
+import { computed } from 'vue'
+import { eraLabel, roundOutward, yearBucketsFromRange } from '../../catalogue/dates.js'
+import { PAGE_SIZE } from '../shared.js'
+
+export { eraLabel, roundOutward }
+
+/**
+ * The exhibition's timeline spec, over its data layer's `data` and the
+ * `PAGE_SIZE`/`tile` its {@link import('./useExhibitionCollection.js').useExhibitionCollection}
+ * already declared.
+ *
+ * Reads `data.exhibition`, `data.timelines`, `data.timelineEvents`,
+ * `data.countries`, `data.countryById`, `data.items`, `data.labelOf`,
+ * `data.tr`, `data.defaultLang`. `config` carries nothing today.
+ */
+export function useExhibitionTimeline(data, collection, config = {}) {
+  void config
+  const { exhibition, timelines, timelineEvents, countries, countryById, items, labelOf, tr, defaultLang } = data
+  const { tile } = collection
+
+  // ── Which chronology this site's Timeline section shows ─────────────────
+  //
+  // An exhibition package carries BOTH chronologies, because the live
+  // instance serves both: `/events` answers the worldwide country merge on
+  // every DXA site, and `/thg/timeline` answers the exhibition's own
+  // narrative one. What decides which the *Timeline pages* show is
+  // `hasCountryBasedTimeline`: legacy's TimelinePage sets
+  // `countriesAvailable` from it and TimelineResults switches its endpoint
+  // on it (`timelineURL = "/thg/timeline?hash="` in the false branch).
+  //
+  // Both flags may be false for an exhibition, and that does NOT mean "no
+  // timeline data". `timelines.json` still ships the worldwide merge in
+  // full — every DXA site gets the worldwide merge whatever its flags say —
+  // possibly with no `thg_local` row at all. The flags gate NAVIGATION, not
+  // data.
+  //
+  // The `thg_local` row has no `country_id`, which is exactly why it must
+  // be separated by `source` rather than left to the country filter: on
+  // "All Countries" it would otherwise be interleaved into the worldwide
+  // list.
+  const localTimeline = computed(
+    () => timelines.value.find((t) => t.source === 'thg_local') ?? null,
+  )
+
+  /** True when the Timeline section is the exhibition's own chronology. */
+  const usesLocalTimeline = computed(
+    () => !exhibition.value?.has_country_timeline && Boolean(localTimeline.value),
+  )
+
+  /**
+   * Whether this site offers a Timeline at all — the one flag every piece
+   * of timeline chrome is gated on.
+   *
+   * Legacy hides more than the nav entry when both chronology flags are
+   * false, which is only visible on a site that has them both false. The
+   * ROUTES stay reachable, because legacy's do: typing /timeline on a live
+   * instance with both flags false still renders the page and its
+   * introduction. Only the links into it are withheld.
+   */
+  const hasTimeline = computed(
+    () => Boolean(exhibition.value?.has_timeline || exhibition.value?.has_country_timeline),
+  )
+
+  /** The events this site's manual Timeline reads (ItemSheet's own popout). */
+  const eventPool = computed(() => {
+    const local = localTimeline.value
+    if (usesLocalTimeline.value) {
+      return timelineEvents.value.filter((e) => e.timeline_id === local.id)
+    }
+    if (!local) return timelineEvents.value
+    return timelineEvents.value.filter((e) => e.timeline_id !== local.id)
+  })
+
+  // The global country timeline, served by legacy `/v2/events`. It is
+  // country-scoped and project-independent, and also a MERGE of two
+  // chronologies rather than one table: legacy's `App\MWNF\DAO\v2\Events`
+  // unions `mwnf3.hcr` (the Discover Islamic Art country chronologies) with
+  // `mwnf3_sharing_history.sh_hcr` restricted to exhibition 2, "Political
+  // Context", and sorts the result by year. The package mirrors that: each
+  // row of `timelines.json` is tagged `source: 'mwnf3' | 'sharing_history'`,
+  // and `timeline_events.json` keys every event by `country_id`.
+  //
+  // A country can be served by BOTH sources, so anything user-facing must
+  // key on the country and never on the timeline row: `findEvents` filters
+  // on `country_id`, which is what merges the two chronologies into one
+  // year-ordered list the way legacy did.
+  //
+  // Names and legacy codes both come from countries.json. The exporter
+  // scopes that file to "member item countries ∪ their holders' countries ∪
+  // the global timeline's countries", so it covers every timeline country —
+  // the `Intl.DisplayNames` fallback below is therefore dead code for them,
+  // and is kept only so a regressed package degrades to a rendered ISO code
+  // rather than a raw id. The `code` countries.json ships is the country's
+  // `backward_compatibility`, which is exactly the code legacy's own
+  // timeline URLs used, including the ones that are not ISO 3166-1
+  // alpha-2 (`uk`, `pa`, `qt`, `rm`, `sb`, `ua`, …). Those are the reason
+  // the fallback must stay unreachable rather than merely rare: read as
+  // ISO, `ua` is Ukraine and `sb` is the Solomon Islands, where legacy
+  // means the UAE and Serbia. Only countries.json can name them correctly.
+  const regionNames = (() => {
+    try {
+      return new Intl.DisplayNames(['en'], { type: 'region' })
+    } catch {
+      return null
+    }
+  })()
+
+  // Two legacy codes are not ISO 3166-1 alpha-2.
+  const LEGACY_TO_ISO = { uk: 'GB', pa: 'PS' }
+
+  // The set of inventory country ids present in countries.json. Ids and
+  // legacy codes are distinct — legacy codes are backward_compatibility
+  // values, while ids are the canonical keys in the inventory system.
+  const countryIdSet = computed(
+    () => new Set(countries.value.map((c) => c.id)),
+  )
+
+  // A lookup, not a parse. The fallback exists only for the
+  // regressed-package case described above, and it must agree with
+  // GLOBAL_TIMELINE_LIKE_PATTERNS in the exporter's timeline exporter: the
+  // country sits after the literal `country` segment in BOTH keyspaces
+  // (`mwnf3:hcr:country:<cc>` and
+  // `mwnf3_sharing_history:sh_hcr:country:<cc>:exhibition:2`), and it is
+  // the last segment in only the first — taking the last one yields `2` on
+  // the second.
+  function legacyCodeOf(timeline) {
+    const fromPackage = countryById.value.get(timeline.country_id)?.code
+    if (fromPackage) return fromPackage
+    const parts = (timeline.backward_compatibility ?? '').split(':')
+    const at = parts.indexOf('country')
+    return (at >= 0 ? parts[at + 1] : null) || timeline.country_id
+  }
+
+  function nameFor(timeline) {
+    const fromPackage = countries.value.some((c) => c.id === timeline.country_id)
+      ? labelOf('countries', timeline.country_id)
+      : null
+    if (fromPackage) return fromPackage
+    const legacy = legacyCodeOf(timeline)
+    const iso = LEGACY_TO_ISO[legacy] ?? String(legacy).toUpperCase()
+    try {
+      return regionNames?.of(iso) ?? iso
+    } catch {
+      return iso
+    }
+  }
+
+  /**
+   * Countries that actually have a chronology, alphabetized, "All" first.
+   *
+   * One entry per COUNTRY, not per timeline row: a country served by BOTH
+   * `mwnf3` and `sharing_history` has two rows, and would otherwise appear
+   * twice in every country picker on the site. Only the item sheet's own
+   * manual "Timeline for this item" picker reads this now — `timelineSpec`
+   * below leaves the picker to viewer-core's `useTimelineEvents`.
+   */
+  const timelineCountries = computed(() => {
+    // No picker at all when the section is the exhibition's own chronology
+    // — legacy hides the select on `countriesAvailable === false`.
+    if (usesLocalTimeline.value) return []
+    const byCountry = new Map()
+    for (const timeline of timelines.value) {
+      if (!timeline.country_id || byCountry.has(timeline.country_id)) continue
+      byCountry.set(timeline.country_id, [legacyCodeOf(timeline), nameFor(timeline)])
+    }
+    const rows = [...byCountry.values()].sort((a, b) => a[1].localeCompare(b[1]))
+    return [['all', 'All Countries'], ...rows]
+  })
+
+  /** Display name for an event's country — also `timelineSpec`'s `countryLabel`. */
+  function timelineCountryName(countryId) {
+    if (countries.value.some((c) => c.id === countryId)) return labelOf('countries', countryId)
+    const timeline = timelines.value.find((t) => t.country_id === countryId)
+    return timeline ? nameFor(timeline) : countryId
+  }
+
+  /**
+   * Legacy 2-letter code → the inventory country id the events are keyed
+   * by. A country served by both chronologies has two rows carrying the
+   * same code and the same `country_id`, so either row answers. Idempotent
+   * on an id already: `TimelineResultsView`'s own country picker offers
+   * ids, so this must resolve BOTH the legacy code a bookmarked or
+   * cross-page link carries and the id the picker itself round-trips.
+   */
+  function countryIdForCode(code) {
+    if (!code || code === 'all') return null
+    if (countryIdSet.value.has(code)) return code
+    if (countryById.value.has(code)) return code
+    const timeline = timelines.value.find((t) => legacyCodeOf(t) === code)
+    if (timeline) return timeline.country_id
+    // Countries with no chronology still reach here from the collection
+    // page's "Timeline for this Search" link, which uses countries.json's
+    // own codes.
+    return countries.value.find((c) => c.code === code)?.id ?? null
+  }
+
+  const eventsTr = (id) => tr('timeline_events', id, defaultLang)
+
+  /**
+   * Legacy's `/events?ic[]=&ya=&yo=` — events for a country within a year
+   * range, ordered chronologically. Kept for the item sheet's own "Timeline
+   * for this item" popout, which reads a single item's country and dates
+   * rather than a URL's filters and has no results page of its own to hand
+   * to `TimelineResultsView`.
+   */
+  function findEvents({ countryCode, start, end }) {
+    const countryId = countryIdForCode(countryCode)
+    const from = start === '' || start == null ? null : Number(start)
+    const to = end === '' || end == null ? null : Number(end)
+
+    return eventPool.value
+      .filter((e) => {
+        if (countryId && e.country_id !== countryId) return false
+        const year = e.year_from
+        if (!Number.isFinite(year)) return false
+        if (from != null && year < from) return false
+        if (to != null && year > to) return false
+        return true
+      })
+      .map((e) => ({
+        ...e,
+        countryName: timelineCountryName(e.country_id),
+        text: eventsTr(e.id),
+      }))
+      .sort((a, b) => (a.year_from - b.year_from) || (a.display_order ?? 0) - (b.display_order ?? 0))
+  }
+
+  // ── The Timeline entrance/results spec ───────────────────────────────
+  //
+  // Feeds `TimelineResultsView`: the engine (viewer-core's
+  // `useTimelineEvents`) owns the country/local axis, the year buckets and
+  // the pagination; an exhibition supplies only what is its own — the
+  // legacy country-code table, the local/country scope switch and the
+  // controls it drives (no country picker when the section is the
+  // exhibition's own chronology), and the "See Gallery" join against
+  // member items, which stays here because an item's own shape (what
+  // counts as "in this period") is the site's, not the package's.
+
+  function yearOptions({ years, t }) {
+    return yearBucketsFromRange(years.min, years.max, t)
+  }
+
+  /** The member items overlapping a country and period, for the gallery link. */
+  function galleryItems({ filters }) {
+    const countryId = countryIdForCode(filters.country)
+    const from = filters.begin ? Number(filters.begin) : null
+    const to = filters.end ? Number(filters.end) : null
+    return items.value.filter((i) => {
+      if (countryId && i.country_id !== countryId) return false
+      const itemStart = i.start_date
+      const itemEnd = i.end_date ?? i.start_date
+      if (!Number.isFinite(itemStart)) return false
+      if (from != null && itemEnd < from) return false
+      if (to != null && itemStart > to) return false
+      return true
+    }).length
+  }
+
+  const timelineSpec = computed(() => ({
+    scope: usesLocalTimeline.value ? 'local' : 'country',
+    countryLabel: timelineCountryName,
+    countryIdForCode,
+    tr: eventsTr,
+    controls: usesLocalTimeline.value
+      ? [{ key: 'begin', options: yearOptions }, { key: 'end', options: yearOptions }]
+      : [{ key: 'country' }, { key: 'begin', options: yearOptions }, { key: 'end', options: yearOptions }],
+    route: 'timeline-results',
+    gallery: { route: 'timeline-gallery', items: galleryItems },
+  }))
+
+  // ── The gallery spec ────────────────────────────────────────────────
+  //
+  // `CatalogueResultsView` over the same country/period join `galleryItems`
+  // counts for the "See Gallery" link above — the query keys are the
+  // results spec's own `begin`/`end` (viewer-layout's `TimelineResultsView`
+  // renders those controls by that name, not `start`/`end`), so the legacy
+  // `/timeline-gallery/:country/:start/:end/:page` redirect is renamed to
+  // match on the way in (the site's own `dataset.config.js`).
+  const timelineGallerySpec = {
+    entity: 'items',
+    keys: ['country', 'begin', 'end'],
+    scope: (item, filters) => {
+      if (!Number.isFinite(item.start_date)) return false
+      const countryId = countryIdForCode(filters.country)
+      return !countryId || item.country_id === countryId
+    },
+    dates: { mode: 'overlap', begin: 'begin', end: 'end' },
+    sort: { undated: 'first' },
+    pageSize: PAGE_SIZE,
+    variant: 'grid',
+    recordRoute: 'item',
+    actionLabel: 'exhibition.action.seeDatabaseEntry',
+    empty: 'exhibition.results.noObjectsInPeriod',
+    record: (item, { t }) => tile(item, t),
+    summary: ({ filters, pageInfo, t }) => [
+      {
+        label: t('timeline.results.galleryHeading'),
+        value: filters.country
+          ? timelineCountryName(countryIdForCode(filters.country))
+          : t('timeline.form.allCountries'),
+      },
+      { count: pageInfo.total, value: t('catalogue.results.objects') },
+    ],
+  }
+
+  return {
+    usesLocalTimeline, hasTimeline, timelineCountries, timelineCountryName, countryIdForCode,
+    findEvents, timelineSpec, timelineGallerySpec,
+  }
+}

package/src/dxa/gallery/useGalleryCollection.js

@@ -0,0 +1,175 @@
+import { projectLabel } from '../../conventions.js'
+import { DATE_MODE, FACET_CATEGORIES, PAGE_SIZE } from '../shared.js'
+
+export { DATE_MODE, FACET_CATEGORIES, FACET_LABEL_KEYS, PAGE_SIZE, useFacetLabels } from '../shared.js'
+
+// The catalogue spec: what a DXA gallery's lists filter and search on. The
+// engine — query state, options, dates, pages, the boolean grammar — is
+// viewer-core's own (`useFacets`, `useListQuery`, …); what is declared here
+// is only what is a gallery's: the facet *predicates* over its own data,
+// the haystack the search bar reads, and the tile a record becomes.
+// `PAGE_SIZE`/`DATE_MODE`/`FACET_CATEGORIES`/`FACET_LABEL_KEYS`/
+// `useFacetLabels` are shared verbatim with the exhibition family — see
+// `../shared.js`.
+//
+// Legacy asked the API for everything: `/items?ic[]=…&id[]=…&na=…&nz=…` for
+// the results, and `/items/countries`, `/items/tags`, `/items/years` *with
+// the same filters applied* for the dropdowns — which is what made the
+// facets dependent (pick a country, and the type list shrinks to the types
+// still reachable). The results page hands the engine the matching subset
+// for that reason; the entrance hands it everything.
+
+/**
+ * The gallery's collection spec, over its own data layer's `data` (the
+ * return value of {@link import('./useGalleryData.js').useGalleryData}).
+ *
+ * Reads `data.countries`, `data.tags`, `data.countryById`, `data.tagById`,
+ * `data.labelOf`, `data.itemRoute`, `data.tr`, `data.defaultLang`,
+ * `data.mdInline` and `data.manifest`. `config` carries nothing today.
+ */
+export function useGalleryCollection(data, config = {}) {
+  void config
+  const { countries, tags, countryById, tagById, labelOf, itemRoute, tr, defaultLang, mdInline, manifest } = data
+
+  // ── What the URL carries ─────────────────────────────────────────────
+  //
+  // The legacy 2-letter country code for `country`, the legacy tag id for a
+  // facet: the values legacy's URLs carried, so a link shared then still
+  // resolves now.
+
+  function countryIdForCode(code) {
+    return code ? (countries.value ?? []).find((c) => c.code === code)?.id ?? null : null
+  }
+
+  function tagIdForLegacy(legacyId) {
+    return legacyId ? (tags.value ?? []).find((t) => t.legacy_tag_id === legacyId)?.id ?? null : null
+  }
+
+  function tagLabelForLegacy(legacyId) {
+    return (tags.value ?? []).find((t) => t.legacy_tag_id === legacyId)?.label ?? legacyId
+  }
+
+  /**
+   * The facet spec for viewer-core's `useFacets`: the country by code, each
+   * tag category by legacy id, labels upper-cased on the first letter as
+   * legacy printed them.
+   */
+  const FACETS = {
+    country: {
+      values: (item) => countryById.value.get(item.country_id)?.code ?? null,
+      label: (code) => labelOf('countries', countryIdForCode(code)),
+    },
+    ...Object.fromEntries(
+      FACET_CATEGORIES.map((category) => [
+        category,
+        {
+          values: (item) =>
+            (item.tag_ids ?? [])
+              .map((id) => tagById.value.get(id))
+              .filter((tag) => tag && tag.category === category)
+              .map((tag) => tag.legacy_tag_id),
+          label: tagLabelForLegacy,
+          capitalize: true,
+        },
+      ]),
+    ),
+  }
+
+  /** The legacy `/items` predicate's tag half: every requested tag, ANDed. */
+  function hasEveryTag(item, tagIds) {
+    return tagIds.every((id) => item.tag_ids?.includes(id))
+  }
+
+  // ── The search bar ───────────────────────────────────────────────────
+  //
+  // Legacy ran MySQL boolean full-text search over the English sheet; the
+  // haystack is the same set of fields, and the grammar is viewer-core's.
+
+  function haystack(item, text) {
+    return [
+      text.name, text.description, text.short_description, text.type, text.holder, text.dates,
+      text.location, text.provenance, text.alternate_name, text.place_of_production,
+      ...(text.keywords ?? []), ...(text.materials ?? []),
+      item.internal_name, item.owner_reference, item.mwnf_reference,
+      labelOf('partners', item.partner_id), labelOf('countries', item.country_id),
+    ]
+  }
+
+  // ── The tile ──────────────────────────────────────────────────────────
+
+  /**
+   * A record as viewer-layout's grid contract: the thumbnail, the name, the
+   * lines legacy's hover card carried (date, holder, place, source
+   * project).
+   */
+  function tile(item, t) {
+    const text = tr('items', item.id, defaultLang)
+    return {
+      id: item.id,
+      image: item.images?.[0]?.url ?? '',
+      imageAlt: labelOf('items', item.id),
+      name: mdInline(text.name ?? item.internal_name ?? ''),
+      meta: [
+        text.dates ?? '',
+        labelOf('partners', item.partner_id),
+        [text.location, labelOf('countries', item.country_id)].filter(Boolean).join(', '),
+        `${t('catalogue.results.forProject')} ${projectLabel(manifest, item.project_id, defaultLang) ?? ''}`,
+      ].filter(Boolean),
+      to: itemRoute(item),
+    }
+  }
+
+  // ── The results page, as a spec ──────────────────────────────────────
+  //
+  // What viewer-layout's `CatalogueResultsView` renders on
+  // `/collection-results`: the facets over the *matching* records (the
+  // dependent dropdowns above), the containment date rule, undated first,
+  // nine tiles a page, legacy's "Collection | <selections>" summary line.
+  // The panel itself is composed by the view's wrapper, in the aside where
+  // legacy put it, so no controls are declared here. Every text is an entry
+  // name.
+
+  // `from`/`to`, not `start`/`end`: the entrance's `SearchFormView` spec
+  // (`mode: 'facets'`, `dates: 'buckets'`) writes the date bounds under
+  // those two fixed keys — the view's own, not something a spec can rename
+  // — so the results side has to read the same ones to stay linked to it.
+  const KEYS = ['country', ...FACET_CATEGORIES, 'from', 'to']
+
+  /** The filter summary line legacy printed as "Collection | <selections>". */
+  function filterSummary(filters, t) {
+    const parts = []
+    if (filters.country) parts.push(labelOf('countries', countryIdForCode(filters.country)))
+    for (const key of FACET_CATEGORIES) if (filters[key]) parts.push(tagLabelForLegacy(filters[key]))
+    if (filters.from) parts.push(`${t('catalogue.filter.from')} ${filters.from}`)
+    if (filters.to) parts.push(`${t('catalogue.filter.to')} ${filters.to}`)
+    return parts.filter(Boolean).join(' | ')
+  }
+
+  const collectionResults = {
+    entity: 'items',
+    keys: KEYS,
+    facets: FACETS,
+    facetScope: 'matching',
+    filterMode: 'immediate',
+    dates: { mode: DATE_MODE, begin: 'from', end: 'to' },
+    sort: { undated: 'first' },
+    pageSize: PAGE_SIZE,
+    variant: 'grid',
+    recordRoute: 'item',
+    actionLabel: 'gallery.action.seeDatabaseEntry',
+    empty: 'catalogue.results.noResults',
+    pagination: { jump: true },
+
+    record: (item, { t }) => tile(item, t),
+
+    summary: ({ filters, pageInfo, t, total }) => [
+      { label: t('gallery.section.collection'), value: filterSummary(filters, t) },
+      { count: pageInfo.total, value: `${t('catalogue.results.outOf')} ${total} ${t('catalogue.results.objects')}` },
+    ],
+  }
+
+  return {
+    FACETS, hasEveryTag, haystack, tile, collectionResults,
+    countryIdForCode, tagIdForLegacy, tagLabelForLegacy,
+  }
+}