@museumwnf/viewer-core 2.2.0 → 2.4.0

package/README.md

@@ -402,7 +402,7 @@ Timeline pages are all one of these three axes over the same event shape.
 
 | Export | Meaning |
 | --- | --- |
-| `useTimelineEvents({ scope, countryLabel, countryIdForCode, tr, timelinesEntity, eventsEntity })` | `{ countries, yearRange, yearBuckets(t), hasTimeline, usesLocalTimeline, findEvents({ country, collection, begin, end }) }`. `scope` is `'country'` (the worldwide merge), `'local'` (an exhibition's own `thg_local` chronology in place of the merge — `countries` is empty, there is nothing to filter by) or `'collection'` (the merge again, plus a `collection` filter on the exhibition a timeline is bound to, `null` meaning the Permanent Collection). `countries` is one entry per country with a chronology, `{ value, label }`, alphabetized, with an `{ value: 'all', label: null }` marker first (never, for `'local'`) — the marker carries no label of its own so a picker names it through its own catalogue entry. `countryLabel(id)` labels a country; the DXA legacy 2-letter code table stays out of this package, so a site passing one instead resolves it through `countryIdForCode(code)`. `tr(id)` returns an event's translated fields, already resolved for entity and language, the same way a site's own data composable already binds it. `findEvents` returns the scope's events in `[begin, end]`, chronological, `display_order` breaking a tie on `year_from`, an event with no year at all last. |
+| `useTimelineEvents({ scope, countryLabel, countryIdForCode, tr, timelinesEntity, eventsEntity })` | `{ countries, yearRange, yearBuckets(t), hasTimeline, usesLocalTimeline, findEvents({ country, collection, begin, end }) }`. `scope` is `'country'` (the worldwide merge), `'local'` (an exhibition's own `thg_local` chronology in place of the merge — `countries` is empty, there is nothing to filter by) or `'collection'` (the merge again, plus a `collection` filter on the exhibition a timeline is bound to, `null` meaning the Permanent Collection). `countries` is one entry per country with a chronology, `{ value, label }`, alphabetized, with an `{ value: 'all', label: null }` marker first (never, for `'local'`) — the marker carries no label of its own so a picker names it through its own catalogue entry. `countryLabel(id)` labels a country; the DXA legacy 2-letter code table stays out of the engine (the DXA families' data layer carries it, `/dxa`), so a caller passing one instead resolves it through `countryIdForCode(code)`. `tr(id)` returns an event's translated fields, already resolved for entity and language, the same way a site's own data composable already binds it. `findEvents` returns the scope's events in `[begin, end]`, chronological, `display_order` breaking a tie on `year_from`, an event with no year at all last. |
 | `overlapsRange(event, begin, end)` | legacy `class.hcr.inc.php`'s overlap rule, standalone: a dated event overlaps once its known end is past `begin` and its start is before `end`; an open-ended event (no known end) overlaps on its start alone; an undated event matches nothing but an unbounded search. |
 | `effectiveYearTo(event)` | `event.year_to`, or `null` when it is `0` or absent — legacy's convention for an open-ended period. |
 | `eventDateLabel(event, text, t)` | the label under an event, trying in order: a narrative chronology's own period name (`text.name` — a sort key there, not a label), a curated description pair (`text.date_from_description` / `text.date_to_description`), and the derived year range through `eraLabel`, for the worldwide merge which has neither. |
@@ -560,12 +560,15 @@ below for whichever future site needs its own).
 
 | Export (gallery / exhibition) | Reads | Returns |
 | --- | --- | --- |
-| `useGalleryData(config)` / `useExhibitionData(config)` | `config.eager` (entity names `loadEnglish` loads eagerly; default the family's own list, the exhibition's also carrying `themes`) | the family's whole data layer: `tr`/`md`/`mdInline`/`mdStrip`/`labelOf`/`loadEnglish`/`translations`, every entity and lookup map (`items`, `partners`, `countries`, `tags`, `dynasties`, `timelines`, `timelineEvents`, …), the routes (`itemRoute`, `partnerRoute`, `partnerObjectsRoute`), the legacy URL wrappers (`itemFromUidPath`, `partnerFromKey` — gallery only), `chromeImage`, `manifest`, `defaultLang`, plus family-specific fields (gallery: `siblingGalleries`/`pickSiblings`; exhibition: `isHiddenPartner`, `isInstitution`, `projectName`, `exhibitionTitle`/`exhibitionSubtitle`/`exhibitionHeadline`/`bannerCaption`, `siblingSites`) |
-| `useGalleryCollection(data, config)` / `useExhibitionCollection(data, config)` | the `data` object above; `config` unused today | `FACETS`, `tile(item, t)`, `collectionResults` (the `CatalogueResultsView` spec), plus the facet-value helpers (`countryIdForCode`, `tagLabelForLegacy`, gallery's own `tagIdForLegacy`, `hasEveryTag`) |
-| `useGalleryTimeline(data, collection, config)` / `useExhibitionTimeline(data, collection, config)` | `data`, the `collection` object above (for its `tile`); `config` unused today | the timeline specs (`timelineResults`/`timelineSpec`, `timelineGallery`/`timelineGallerySpec`) and their helpers (`countryLabel`/`countryIdForCode`, `timelineGalleryItems`; the exhibition shape adds `usesLocalTimeline`, `hasTimeline`, `timelineCountries`, `findEvents` for its own local-vs-country chronology switch) |
+| `useGalleryData(config)` / `useExhibitionData(config)` | `config.eager` (entity names `loadEnglish` loads eagerly; default the family's own list, the exhibition's also carrying `themes`) | the family's whole data layer: `tr`/`md`/`mdInline`/`mdStrip`/`labelOf`/`loadEnglish`/`translations`, every entity and lookup map (`items`, `partners`, `countries`, `tags`, `dynasties`, `timelines`, `timelineEvents`, …), the routes (`itemRoute`, `partnerRoute`, `partnerObjectsRoute`), the legacy URL wrappers (`itemFromUidPath`, `partnerFromKey` — gallery only), the DXA legacy country code both ways (`countryIdForCode(code)`, idempotent on an id, and `countryLabel(countryId)`, one table the collection and the timeline both read), `chromeImage`, `manifest`, `defaultLang`, plus family-specific fields (gallery: `siblingGalleries`/`pickSiblings`; exhibition: `isHiddenPartner`, `isInstitution`, `projectName`, `exhibitionTitle`/`exhibitionSubtitle`/`exhibitionHeadline`/`bannerCaption`, `siblingSites`) |
+| `useGalleryCollection(data, config)` / `useExhibitionCollection(data, config)` | the `data` object above; `config` unused today | `FACETS`, `tile(item, t)`, `collectionResults` (the `CatalogueResultsView` spec), plus the facet-value helpers (`countryIdForCode` — the data layer's —, `tagLabelForLegacy`, gallery's own `tagIdForLegacy`, `hasEveryTag`) |
+| `useGalleryTimeline(data, collection, config)` / `useExhibitionTimeline(data, collection, config)` | `data`, the `collection` object above (for its `tile`); `config` unused today | the timeline specs (`timelineResults`/`timelineSpec`, `timelineGallery`/`timelineGallerySpec`), `timelineEvents` (viewer-core's `useTimelineEvents` engine — for an exhibition, the one its flags put in force, country or local), and the data layer's `countryLabel`/`countryIdForCode`; the gallery adds `timelineGalleryItems`, the exhibition `usesLocalTimeline` and `hasTimeline` for its local-vs-country chronology switch |
 | `useGalleryPartner(data, collection, config)` / `useExhibitionPartner(data, config)` | `data`, and (gallery only) `collection` for its `tile` | `partnerList`/`partnerListSpec`, `partnerSheet`/`partnerSheetSpec`, and (gallery only) `partnerObjects` — the exhibition shape's `partnerSpecs.js` never carried an objects-page spec |
 | `useGallerySheet(data, config)` / `useExhibitionSheet(data, config)` | `data`; `config` unused today | `{ itemSheet }`, the `RecordView` spec — the exhibition shape's `citation.project` reads `data.projectName`, absent from the gallery shape |
 | `PAGE_SIZE`, `DATE_MODE`, `FACET_CATEGORIES`, `FACET_LABEL_KEYS`, `useFacetLabels()` | — | the five THG catalogue facets, shared verbatim by both families (nine tiles a page, containment dates, `type`/`dynasty`/`subject`/`material`/`artist`) |
+| `useGalleryItemDetail(data, timeline)` / `useExhibitionItemDetail(data, timeline)` | `data`, the family's `timeline` object; the site's `projectColors` and `noticeProjects` through `useSiteConfig()`, read lazily | `{ itemDetail }`, the item page's `RecordSheetView` spec: the family sheet plus the source-database chip, the Explore-partner notice, the holding-museum link (none for an exhibition's hidden partner), and the related block's labels, outside-reference chips, dynasty popouts and timeline popout. The exhibition gives a record with no project the `mwnf-chip--Explore` chip, and its "search this period" link carries only the timeline controls' keys |
+| `useExhibitionThemes(data)` | `data` | the exhibition's themes: `themeTree` (a `useCollectionTree` over themes.json, `entity: 'themes'`), `themes`, `aboutTheme`, `listedThemes`, `themeByRouteId`/`themeRouteId` (legacy's `display_order - 1`), `romanFor`, `themePictures`, `pictureById`, `themeText`/`pictureText`, `owningTheme`, `subIndexOf`, `pictureParent`, `itemDetailString`, and `useThemePictures(node)`, the live `pictures` `PictureGallery`/`PictureNarrative` read |
+| `buildThemePictures(nodePictures, deps)`, `romanFor(displayOrder)` | — | the pure halves of the above: a node's pictures with their `related`/`backRelated` links resolved across the whole tree, and legacy's Roman theme numeral (display order 2 is "I") |
 
 ### The declaration outside a component
 

package/package.json

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

package/src/dxa/countryCodes.js

@@ -0,0 +1,92 @@
+import { computed } from 'vue'
+
+// The DXA legacy country code, the one a gallery's or an exhibition's URLs
+// carry (`?country=eg`, the facet values, the timeline's own links), and the
+// inventory id the records are keyed by (`egy`). Both families read it for
+// their collection and their timeline through this one table
+// (inventory-app#2056); each of the four once defined its own.
+//
+// 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 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.
+
+// Two legacy codes are not ISO 3166-1 alpha-2.
+const LEGACY_TO_ISO = { uk: 'GB', pa: 'PS' }
+
+const regionNames = (() => {
+  try {
+    return new Intl.DisplayNames(['en'], { type: 'region' })
+  } catch {
+    return null
+  }
+})()
+
+/**
+ * The legacy country code both ways, over a family data layer's
+ * `countries`, `countryById`, `timelines` and `labelOf`.
+ *
+ * - `countryIdForCode(code)`: the inventory id for a legacy code; idempotent
+ *   on an id (the composed views' own country controls write ids), `null`
+ *   for none, `'all'` or an unknown code.
+ * - `countryLabel(countryId)`: a country's name, for one countries.json
+ *   lacks too (read off its timeline row).
+ */
+export function useLegacyCountryCodes({ countries, countryById, timelines, labelOf }) {
+  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) {
+    if (countryIdSet.value.has(timeline.country_id)) return labelOf('countries', timeline.country_id)
+    const legacy = legacyCodeOf(timeline)
+    const iso = LEGACY_TO_ISO[legacy] ?? String(legacy).toUpperCase()
+    try {
+      return regionNames?.of(iso) ?? iso
+    } catch {
+      return iso
+    }
+  }
+
+  function countryLabel(countryId) {
+    if (countryIdSet.value.has(countryId)) return labelOf('countries', countryId)
+    const timeline = (timelines.value ?? []).find((t) => t.country_id === countryId)
+    return timeline ? nameFor(timeline) : countryId
+  }
+
+  // A country served by both chronologies has two timeline rows carrying the
+  // same code and the same `country_id`, so either row answers.
+  function countryIdForCode(code) {
+    if (!code || code === 'all') return null
+    // Already an id: pass it through unchanged, before the legacy-code
+    // lookups below get a chance to find nothing and match every record.
+    if (countryIdSet.value.has(code)) return code
+    const timeline = (timelines.value ?? []).find((t) => legacyCodeOf(t) === code)
+    if (timeline) return timeline.country_id
+    // A country with no chronology: countries.json's own code.
+    return (countries.value ?? []).find((c) => c.code === code)?.id ?? null
+  }
+
+  return { countryIdForCode, countryLabel }
+}

package/src/dxa/exhibition/useExhibitionCollection.js

@@ -22,26 +22,22 @@ export { DATE_MODE, FACET_CATEGORIES, FACET_LABEL_KEYS, PAGE_SIZE, useFacetLabel
  * The exhibition's collection spec, over its own data layer's `data` (the
  * return value of {@link import('./useExhibitionData.js').useExhibitionData}).
  *
- * Reads `data.countries`, `data.tags`, `data.countryById`, `data.tagById`,
- * `data.itemById`, `data.labelOf`, `data.itemRoute`, `data.tr`,
- * `data.defaultLang`, `data.mdInline`, `data.projectName`. `config` carries
- * nothing today.
+ * Reads `data.tags`, `data.countryById`, `data.tagById`, `data.itemById`,
+ * `data.labelOf`, `data.itemRoute`, `data.tr`, `data.defaultLang`,
+ * `data.mdInline`, `data.projectName`, `data.countryIdForCode`. `config`
+ * carries nothing today.
  */
 export function useExhibitionCollection(data, config = {}) {
   void config
   const {
-    countries, tags, countryById, tagById, itemById, labelOf, itemRoute, tr, defaultLang, mdInline, projectName,
+    tags, countryById, tagById, itemById, labelOf, itemRoute, tr, defaultLang, mdInline, projectName, countryIdForCode,
   } = 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
-  }
+  // The legacy 2-letter country code for `country` (the data layer's
+  // `countryIdForCode`), the legacy tag id for a facet: the values legacy's
+  // URLs carried, so a link shared then still resolves now.
 
   function tagLabelForLegacy(legacyId) {
     return (tags.value ?? []).find((t) => t.legacy_tag_id === legacyId)?.label ?? legacyId

package/src/dxa/exhibition/useExhibitionData.js

@@ -4,6 +4,7 @@ import { useCatalogueData } from '../../composables/useCatalogueData.js'
 import { useDataPackage } from '../../composables/useDataPackage.js'
 import { byId, entityRef } from '../../composables/useEntities.js'
 import { projectLabel } from '../../conventions.js'
+import { useLegacyCountryCodes } from '../countryCodes.js'
 
 // The data layer every DXA exhibition site (the-use-of-colours-in-art,
 // water-in-islam, …) wrote for itself: the entities an exhibition reads,
@@ -134,6 +135,10 @@ export function useExhibitionData(config = {}) {
     return country ? labelOf('countries', country.id) : code
   }
 
+  // The legacy code both ways, the one table the collection and the
+  // timeline read.
+  const { countryIdForCode, countryLabel } = useLegacyCountryCodes({ countries, countryById, timelines, labelOf })
+
   /** The canonical item route: the package id, and no language in the path. */
   function itemRoute(item) {
     return { name: 'item', params: { id: item.id } }
@@ -236,7 +241,7 @@ export function useExhibitionData(config = {}) {
     tr, md, mdInline, mdStrip, labelOf, loadEnglish, availableLanguages, loadTranslations, translations,
     chromeImage,
     partnerById, countryById, tagById, dynastyById, glossaryById, languageByCode,
-    countryByCode, countryLabelFromCode,
+    countryByCode, countryLabelFromCode, countryIdForCode, countryLabel,
     itemRoute, isInstitution, partnerRoute, partnerObjectsRoute,
     isExploreRecord, projectName,
     exhibitionTitle, exhibitionSubtitle, exhibitionHeadline, bannerCaption,

package/src/dxa/exhibition/useExhibitionItemDetail.js

@@ -0,0 +1,131 @@
+import { eraLabel, roundOutward } from '../../catalogue/dates.js'
+import { useSiteConfig } from '../../siteConfig.js'
+import { useExhibitionSheet } from './useExhibitionSheet.js'
+
+// An exhibition's item page, as viewer-layout's `RecordSheetView` spec
+// (inventory-app#2053): `useExhibitionSheet`'s field sheet, plus the blocks
+// the view reads through `spec.sourceDatabase`, `spec.notice`, `spec.museum`
+// and `spec.related.*`. The six exhibitions each carried this layer as their
+// own `composables/sheet.js`, the same code in all six.
+//
+// What stays an exhibition's own is read from its `dataset.config.js`
+// through `useSiteConfig()`, lazily, as the galleries do:
+//
+//   * `projectColors`, project id → one of viewer-layout's `mwnf-chip--*`
+//     classes, for the source-database chip and an outside reference's chip;
+//     a record with no project at all is an Explore record, whose chip is
+//     `mwnf-chip--Explore`;
+//   * `noticeProjects`, the projects whose sheets still carry legacy's
+//     Explore-partner notice.
+
+/**
+ * The exhibition's item-page spec, over its data layer's `data` and its
+ * timeline layer's `timeline` (`useExhibitionTimeline`).
+ *
+ * Reads `data.defaultLang`, `data.dynastyById`, `data.isExploreRecord`,
+ * `data.isHiddenPartner`, `data.labelOf`, `data.partnerById`,
+ * `data.partnerRoute`, `data.translations`, what `useExhibitionSheet` reads,
+ * and `timeline.countryIdForCode`, `timeline.hasTimeline`,
+ * `timeline.timelineEvents` (`countries`, `findEvents`), `timeline.timelineSpec`.
+ */
+export function useExhibitionItemDetail(data, timeline) {
+  const {
+    defaultLang, dynastyById, isExploreRecord, isHiddenPartner, labelOf, partnerById, partnerRoute, translations,
+  } = data
+  const { countryIdForCode, hasTimeline, timelineEvents, timelineSpec } = timeline
+  const { countries: timelineCountries, findEvents } = timelineEvents
+  const { itemSheet: platformSheet } = useExhibitionSheet(data)
+
+  function chipClass(record) {
+    return useSiteConfig().projectColors?.[record.project_id] ?? (isExploreRecord(record) ? 'mwnf-chip--Explore' : null)
+  }
+
+  function dynastyTr(dynasty, language) {
+    return translations('dynasties', language)[dynasty.id] ?? translations('dynasties', defaultLang)[dynasty.id] ?? {}
+  }
+
+  // Legacy popped out a dynasty only when it had a history to show.
+  function dynastiesWithHistory(record, language) {
+    return (record.dynasty_ids ?? [])
+      .map((id) => dynastyById.value.get(id))
+      .filter((d) => d && dynastyTr(d, language).history)
+  }
+
+  // The country the "Timeline for this item" popout opens on: the picker's
+  // entry for the record's own country.
+  function countryOf(countryId) {
+    for (const { value } of timelineCountries.value) {
+      if (countryIdForCode(value) === countryId) return value
+    }
+    return null
+  }
+
+  // The popout's "search this period" link: the timeline results filtered to
+  // the country and the period, under the keys the results page's controls
+  // read — never a key it has no control for (a local timeline has no
+  // country), which it would ignore (inventory-app#2022).
+  function periodSearch(country, range) {
+    const keys = new Set((timelineSpec.value?.controls ?? []).map((control) => control.key))
+    const query = { country, begin: range[0], end: range[1] }
+    return { name: 'timeline-results', query: Object.fromEntries(Object.entries(query).filter(([key]) => keys.has(key))) }
+  }
+
+  const itemDetail = {
+    ...platformSheet,
+
+    sourceDatabase: {
+      chipClass: (record) => chipClass(record),
+    },
+
+    notice: {
+      show: (record) => (useSiteConfig().noticeProjects ?? []).includes(record.project_id),
+      label: 'exhibition.item.explorePartnerNote',
+    },
+
+    // A hidden museum keeps its name on the sheet and loses the link: it has
+    // no page to link to.
+    museum: {
+      route: (partnerId) => {
+        const partner = partnerById.value.get(partnerId)
+        if (!partner || isHiddenPartner(partner)) return null
+        return partnerRoute(partner)
+      },
+      label: (partnerId) => labelOf('partners', partnerId),
+    },
+
+    related: {
+      ...platformSheet.related,
+      title: 'exhibition.related.title',
+      description: 'exhibition.related.description',
+      outsideChip: (ref) => chipClass(ref),
+      notInPackageLabel: 'exhibition.results.notInThisExhibition',
+      artisticIntroductionLabel: 'exhibition.nav.artisticIntroduction',
+      databaseLabel: 'exhibition.search.relatedDatabase',
+      overallDatabase: { label: 'exhibition.search.overallDatabase', linkLabel: 'exhibition.nav.overallDatabase' },
+      onDisplayIn: { linkPendingLabel: 'exhibition.item.linkPending' },
+      dynasties: (record, language) => ({
+        records: dynastiesWithHistory(record, language),
+        tr: (d) => dynastyTr(d, language),
+      }),
+      // Withheld when the exhibition reports no chronology, or the item has
+      // no date to anchor a range on: legacy then printed no "timeline"
+      // anywhere on the sheet.
+      timeline: (record, ctx) => {
+        if (!hasTimeline.value) return null
+        const range = roundOutward(record.start_date, record.end_date)
+        if (range[0] == null) return null
+        return {
+          heading: 'exhibition.section.timeline',
+          countries: timelineCountries.value.map((c) => ({ value: c.value, label: c.label ?? ctx.t('timeline.form.allCountries') })),
+          defaultCountry: () => countryOf(record.country_id) ?? 'all',
+          events: (country) => findEvents({ country, begin: range[0], end: range[1] }),
+          range,
+          era: (year) => eraLabel(year, ctx.t),
+          searchTo: periodSearch,
+        }
+      },
+    },
+  }
+
+  return { itemDetail }
+}

package/src/dxa/exhibition/useExhibitionThemes.js

@@ -0,0 +1,279 @@
+import { computed } from 'vue'
+import { useI18n } from '../../i18n/index.js'
+import { entityRef } from '../../composables/useEntities.js'
+import { useCollectionTree } from '../../record/collectionTree.js'
+
+// An exhibition's themes: the tour its theme pages, its themes list and its
+// theme galleries read (inventory-app#2053). The six exhibitions each carried
+// this as `composables/themes.js`, `useThemePresentation.js` and
+// `useThemePictures.js`, the same code in all six.
+//
+// themes.json is the ordered tree: top-level themes, each with its sub-themes
+// and its curated picture selections. `useCollectionTree({ source: 'themes' })`
+// walks it, and its `previous`/`next` (depth-first) is legacy's tour order:
+// About → theme 1 overview → its sub-themes → theme 2 overview → ….
+//
+// Two rules the data fixes rather than taste:
+//
+//   * Theme 0 ("About the Exhibition") is an ordinary top-level theme legacy
+//     renders at /about and skips on /themes. Its display order is 1, so the
+//     themes list starts at display order 2 and numbers those "Theme I"
+//     upwards — which is why `romanFor` subtracts one.
+//   * The theme id in the keyspace is not the display order. The route
+//     carries `display_order - 1`, as legacy's `theme.display - 1` did, so a
+//     legacy address pasted after the `#` lands on the same theme.
+//
+// A theme's selections point at `picture` items, which are not members of the
+// exhibition and so not in items.json — only their parents are. Every label a
+// theme page shows (name, holding museum, location, country) is read off the
+// parent record, which is also what "see the full record" links to.
+// `parent_in_package` says whether the parent is there at all: a curated
+// picture whose parent was not exported still renders its own image.
+
+/**
+ * Legacy numbered its themes in Roman numerals, counting from the About
+ * theme. EssayView's `numbering: 'roman'` counts a node's position among its
+ * siblings, which it derives from `tree.root` — always null for a themes.json
+ * package — so it would number every top-level theme "I". The numeral an
+ * exhibition shows is always the owning theme's, so one function serves
+ * themes and sub-themes.
+ */
+export function romanFor(displayOrder) {
+  const lookup = [
+    ['M', 1000], ['CM', 900], ['D', 500], ['CD', 400], ['C', 100], ['XC', 90],
+    ['L', 50], ['XL', 40], ['X', 10], ['IX', 9], ['V', 5], ['IV', 4], ['I', 1],
+  ]
+  let n = displayOrder - 1
+  let out = ''
+  for (const [sym, value] of lookup) {
+    while (n >= value) { out += sym; n -= value }
+  }
+  return out
+}
+
+/**
+ * The `pictures` PictureGallery/PictureNarrative read (viewer-layout's
+ * docs/theme-components.md) for one node, as a pure function of its data so
+ * the graph rules are tested without Vue or a package.
+ *
+ * A picture's `related`/`backRelated` targets resolve against `pictureById`,
+ * the WHOLE tree's picture index, not the node's own selections:
+ * `theme_item_related` rows can name a picture curated under another theme,
+ * and scoping the lookup to the node is what used to drop such a link.
+ *
+ * @param nodePictures - the node's own selections, in curator order
+ * @param deps.pictureById - Map<pictureId, rawPicture> for every picture in the tree
+ * @param deps.resolvePicture - (raw) => `{ id, image, imageAlt, name, detail, to }`,
+ *   the node-independent shape, used for the node's pictures and every target
+ * @param deps.imageCaptionFor - (raw) => this node's own caption for the picture
+ * @param deps.fieldsFor - (raw) => this node's panel `fields` for the picture
+ * @param deps.relationText - (link) => the forward relation's text
+ * @param deps.reciprocalText - (link) => the backward relation's text
+ */
+export function buildThemePictures(nodePictures, deps) {
+  const {
+    pictureById: byId, resolvePicture, imageCaptionFor, fieldsFor, relationText, reciprocalText,
+  } = deps
+
+  return (nodePictures ?? []).map((raw) => {
+    const related = (raw.related ?? [])
+      .map((link) => {
+        const target = byId.get(link.picture_item_id)
+        return target ? { picture: resolvePicture(target), text: relationText(link) } : null
+      })
+      .filter(Boolean)
+
+    // Every other picture anywhere in the tree whose own `related` names this
+    // one, so a target on another theme's page still shows "related to" back.
+    const backRelated = []
+    for (const other of byId.values()) {
+      for (const link of other.related ?? []) {
+        if (link.picture_item_id === raw.picture_item_id) {
+          backRelated.push({ picture: resolvePicture(other), reciprocalText: reciprocalText(link) })
+        }
+      }
+    }
+
+    return {
+      ...resolvePicture(raw),
+      imageCaption: imageCaptionFor(raw),
+      fields: fieldsFor(raw),
+      // Not part of the components' contract: the theme page turns a
+      // selection back into legacy's `?image=<display_order>` with it.
+      displayOrder: raw.display_order,
+      related,
+      backRelated,
+    }
+  })
+}
+
+/**
+ * The exhibition's themes, over its data layer's `data`.
+ *
+ * Reads `data.defaultLang`, `data.itemById`, `data.itemRoute`, `data.labelOf`,
+ * `data.mdInline`, `data.tr`.
+ */
+export function useExhibitionThemes(data) {
+  const { defaultLang, itemById, itemRoute, labelOf, mdInline, tr } = data
+
+  // EssayView reads `spec.tree.entity` to know where a node's own text lives,
+  // even for a tree built here rather than from its `{ themes: true }`
+  // shorthand; without it, every title/quote/body lookup would read
+  // 'collections', not a themes.json package's entity.
+  const themeTree = useCollectionTree({ source: 'themes', entity: 'themes' })
+  themeTree.entity = 'themes'
+
+  // The raw top-level array, in the order the themes list and the tour read
+  // them: the tree's own `root` is always null for this shape, so it cannot
+  // hand back every top-level theme itself.
+  const rawThemes = entityRef('themes')
+  const themes = computed(() => rawThemes.value ?? [])
+
+  const aboutTheme = computed(() => themes.value.find((t) => t.display_order === 1) ?? null)
+
+  /** The themes the themes page lists: everything after the About theme. */
+  const listedThemes = computed(() => themes.value.filter((t) => t.display_order > 1))
+
+  /** Route id → theme: legacy's `/theme/:id` carries `display_order - 1`. */
+  function themeByRouteId(id) {
+    const n = Number(id)
+    return themes.value.find((t) => t.display_order - 1 === n) ?? null
+  }
+
+  function themeRouteId(theme) {
+    return (theme?.display_order ?? 1) - 1
+  }
+
+  /** A node's picture selections, in curator order. */
+  function themePictures(theme) {
+    return [...(theme?.pictures ?? [])].sort((a, b) => (a.display_order ?? 0) - (b.display_order ?? 0))
+  }
+
+  /** Every picture selection in the tree, by its own id (not a catalogue id). */
+  const pictureById = computed(() => {
+    const map = new Map()
+    for (const node of themeTree.byId.value.values()) {
+      for (const picture of node.pictures ?? []) map.set(picture.picture_item_id, picture)
+    }
+    return map
+  })
+
+  // translations/themes.<lang>.json is keyed two ways: by theme id for the
+  // theme's own title/quote/presentation, and by `<theme id>/<picture item
+  // id>` for one picture's curated text in that theme — the same picture in
+  // two themes carries two descriptions.
+  function themeText(theme, lang = defaultLang) {
+    return tr('themes', theme?.id, lang)
+  }
+
+  function pictureText(theme, picture, lang = defaultLang) {
+    if (!theme?.id || !picture?.picture_item_id) return {}
+    return tr('themes', `${theme.id}/${picture.picture_item_id}`, lang)
+  }
+
+  /** The top-level theme that owns a node: the node itself, or its parent. */
+  function owningTheme(node) {
+    if (!node) return null
+    const parents = themeTree.parents(node.id)
+    return parents.length ? parents[0] : node
+  }
+
+  /** A node's 1-based position among its owning theme's sub-themes; null for the theme itself. */
+  function subIndexOf(node) {
+    if (!node) return null
+    const owner = owningTheme(node)
+    if (!owner || owner.id === node.id) return null
+    const index = themeTree.children(owner.id).findIndex((child) => child.id === node.id)
+    return index === -1 ? null : index + 1
+  }
+
+  /** A picture selection's parent record, or null when it is not a member. */
+  function pictureParent(picture) {
+    if (!picture?.parent_in_package) return null
+    return itemById.value.get(picture.parent_item_id) ?? null
+  }
+
+  /** Legacy's `itemDetailString`: museum, location, country, blanks dropped. */
+  function itemDetailString(item) {
+    if (!item) return ''
+    const sheet = tr('items', item.id, defaultLang)
+    return [
+      sheet.holder || labelOf('partners', item.partner_id),
+      sheet.location,
+      labelOf('countries', item.country_id),
+    ].filter(Boolean).join(', ')
+  }
+
+  /**
+   * A node's `pictures`, live: its selections resolved against the parent
+   * records, the translations and the current locale. Call it in a
+   * component's setup; `node` is a ref.
+   */
+  function useThemePictures(node) {
+    const { t, locale } = useI18n()
+
+    function resolvePicture(raw) {
+      const parent = pictureParent(raw)
+      const name = parent ? labelOf('items', parent.id) : ''
+      return {
+        id: raw.picture_item_id,
+        image: raw.image_url,
+        imageAlt: name,
+        name: mdInline(name),
+        detail: itemDetailString(parent),
+        to: parent ? itemRoute(parent) : null,
+      }
+    }
+
+    function imageCaptionFor(raw) {
+      if (!node.value?.id) return ''
+      return tr('themes', `${node.value.id}/${raw.picture_item_id}`, locale.value).image_caption ?? ''
+    }
+
+    // Legacy labelled only "also known as"; artist names and dates stand
+    // alone, as `fields` rows with an empty label.
+    function fieldsFor(raw) {
+      const parent = pictureParent(raw)
+      if (!parent) return []
+      const sheet = tr('items', parent.id, defaultLang)
+      const fields = []
+      if (sheet.alternate_name) {
+        fields.push({ label: `${t('sheet.field.alsoKnownAs')}:`, value: mdInline(sheet.alternate_name) })
+      }
+      if (parent.artist_names?.length) fields.push({ label: '', value: parent.artist_names.join(', ') })
+      if (sheet.dates) fields.push({ label: '', value: sheet.dates })
+      return fields
+    }
+
+    const relationText = (link) => link?.descriptions?.[locale.value] ?? link?.descriptions?.en ?? ''
+    const reciprocalText = (link) => link?.reciprocal_descriptions?.[locale.value] ?? link?.reciprocal_descriptions?.en ?? ''
+
+    return computed(() => buildThemePictures(themePictures(node.value), {
+      pictureById: pictureById.value,
+      resolvePicture,
+      imageCaptionFor,
+      fieldsFor,
+      relationText,
+      reciprocalText,
+    }))
+  }
+
+  return {
+    themeTree,
+    themes,
+    aboutTheme,
+    listedThemes,
+    themeByRouteId,
+    themeRouteId,
+    romanFor,
+    themePictures,
+    pictureById,
+    themeText,
+    pictureText,
+    owningTheme,
+    subIndexOf,
+    pictureParent,
+    itemDetailString,
+    useThemePictures,
+  }
+}

package/src/dxa/exhibition/useExhibitionTimeline.js

@@ -1,5 +1,6 @@
 import { computed } from 'vue'
 import { eraLabel, roundOutward, yearBucketsFromRange } from '../../catalogue/dates.js'
+import { useTimelineEvents } from '../../catalogue/timeline.js'
 import { PAGE_SIZE } from '../shared.js'
 
 export { eraLabel, roundOutward }
@@ -9,13 +10,13 @@ export { eraLabel, roundOutward }
  * `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.
+ * Reads `data.exhibition`, `data.timelines`, `data.items`, `data.tr`,
+ * `data.defaultLang`, `data.countryIdForCode`, `data.countryLabel`.
+ * `config` carries nothing today.
  */
 export function useExhibitionTimeline(data, collection, config = {}) {
   void config
-  const { exhibition, timelines, timelineEvents, countries, countryById, items, labelOf, tr, defaultLang } = data
+  const { exhibition, timelines, items, tr, defaultLang, countryIdForCode, countryLabel } = data
   const { tile } = collection
 
   // ── Which chronology this site's Timeline section shows ─────────────────
@@ -33,13 +34,8 @@ export function useExhibitionTimeline(data, collection, config = {}) {
   // 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,
+    () => (timelines.value ?? []).find((t) => t.source === 'thg_local') ?? null,
   )
 
   /** True when the Timeline section is the exhibition's own chronology. */
@@ -61,180 +57,39 @@ export function useExhibitionTimeline(data, collection, config = {}) {
     () => 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 events ───────────────────────────────────────────────────────
+  //
+  // viewer-core's `useTimelineEvents` is the one engine over both
+  // chronologies: the worldwide country merge (`scope: 'country'`, which
+  // keeps the `thg_local` row out of it by `source`, since that row has no
+  // country to filter on) and the exhibition's own narrative one
+  // (`scope: 'local'`). The exhibition's flags pick between them once the
+  // exhibition record has loaded, so both are built and `timelineEvents`
+  // reads the one in force. The item page's "Timeline for this item" popout
+  // reads it; the Timeline pages build their own from `timelineSpec` below.
+  const engine = { countryLabel, countryIdForCode, tr: eventsTr }
+  const countryEvents = useTimelineEvents({ scope: 'country', ...engine })
+  const localEvents = useTimelineEvents({ scope: 'local', ...engine })
+  const inForce = () => (usesLocalTimeline.value ? localEvents : countryEvents)
+
+  const timelineEvents = {
+    countries: computed(() => inForce().countries.value),
+    yearRange: computed(() => inForce().yearRange.value),
+    yearBuckets: (t) => inForce().yearBuckets(t),
+    findEvents: (filters) => inForce().findEvents(filters),
   }
 
   // ── 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.
+  // Feeds `TimelineResultsView`: the engine owns the country/local axis,
+  // the year buckets and the pagination; an exhibition supplies only what
+  // is its own — 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)
@@ -258,7 +113,7 @@ export function useExhibitionTimeline(data, collection, config = {}) {
 
   const timelineSpec = computed(() => ({
     scope: usesLocalTimeline.value ? 'local' : 'country',
-    countryLabel: timelineCountryName,
+    countryLabel,
     countryIdForCode,
     tr: eventsTr,
     controls: usesLocalTimeline.value
@@ -275,7 +130,7 @@ export function useExhibitionTimeline(data, collection, config = {}) {
   // 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`).
+  // match on the way in.
   const timelineGallerySpec = {
     entity: 'items',
     keys: ['country', 'begin', 'end'],
@@ -296,7 +151,7 @@ export function useExhibitionTimeline(data, collection, config = {}) {
       {
         label: t('timeline.results.galleryHeading'),
         value: filters.country
-          ? timelineCountryName(countryIdForCode(filters.country))
+          ? countryLabel(countryIdForCode(filters.country))
           : t('timeline.form.allCountries'),
       },
       { count: pageInfo.total, value: t('catalogue.results.objects') },
@@ -304,7 +159,7 @@ export function useExhibitionTimeline(data, collection, config = {}) {
   }
 
   return {
-    usesLocalTimeline, hasTimeline, timelineCountries, timelineCountryName, countryIdForCode,
-    findEvents, timelineSpec, timelineGallerySpec,
+    usesLocalTimeline, hasTimeline, countryLabel, countryIdForCode,
+    timelineEvents, timelineSpec, timelineGallerySpec,
   }
 }

package/src/dxa/gallery/useGalleryCollection.js

@@ -23,23 +23,20 @@ export { DATE_MODE, FACET_CATEGORIES, FACET_LABEL_KEYS, PAGE_SIZE, useFacetLabel
  * 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.
+ * Reads `data.tags`, `data.countryById`, `data.tagById`, `data.labelOf`,
+ * `data.itemRoute`, `data.tr`, `data.defaultLang`, `data.mdInline`,
+ * `data.manifest` and `data.countryIdForCode`. `config` carries nothing
+ * today.
  */
 export function useGalleryCollection(data, config = {}) {
   void config
-  const { countries, tags, countryById, tagById, labelOf, itemRoute, tr, defaultLang, mdInline, manifest } = data
+  const { tags, countryById, tagById, labelOf, itemRoute, tr, defaultLang, mdInline, manifest, countryIdForCode } = 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
-  }
+  // The legacy 2-letter country code for `country` (the data layer's
+  // `countryIdForCode`), the legacy tag id for a facet: the values legacy's
+  // URLs carried, so a link shared then still resolves now.
 
   function tagIdForLegacy(legacyId) {
     return legacyId ? (tags.value ?? []).find((t) => t.legacy_tag_id === legacyId)?.id ?? null : null

package/src/dxa/gallery/useGalleryData.js

@@ -3,6 +3,7 @@ import { mediaUrl } from '../../siteConfig.js'
 import { useCatalogueData } from '../../composables/useCatalogueData.js'
 import { useDataPackage } from '../../composables/useDataPackage.js'
 import { itemFromUidPath as legacyItemFromUidPath, partnerFromKey as legacyPartnerFromKey } from '../../legacy/index.js'
+import { useLegacyCountryCodes } from '../countryCodes.js'
 
 // The data layer every DXA gallery site (carpets, amulets, …) wrote for
 // itself: the entities a gallery reads, the lookup maps over them, its
@@ -62,6 +63,10 @@ export function useGalleryData(config = {}) {
   const timelineById = catalogue.index('timelines')
   const languageByCode = catalogue.index('languages', 'code')
 
+  // The legacy country code both ways, the one table the collection and the
+  // timeline read.
+  const { countryIdForCode, countryLabel } = useLegacyCountryCodes({ countries, countryById, timelines, labelOf })
+
   // ── Routes ─────────────────────────────────────────────────────────────
   //
   // The canonical routes carry the package id; the language never travels
@@ -137,6 +142,7 @@ export function useGalleryData(config = {}) {
     availableLanguages, loadTranslations, translations,
     gallery, items, tags, partners, countries, languages, dynasties, glossary, timelines, timelineEvents,
     itemById, partnerById, countryById, tagById, dynastyById, timelineById, languageByCode,
+    countryIdForCode, countryLabel,
     itemRoute, partnerRoute, partnerObjectsRoute, itemFromUidPath, partnerFromKey,
     chromeImage, siblingGalleries, siblingUrl, pickSiblings,
   }

package/src/dxa/gallery/useGalleryItemDetail.js

@@ -0,0 +1,110 @@
+import { eraLabel, roundOutward } from '../../catalogue/dates.js'
+import { useSiteConfig } from '../../siteConfig.js'
+import { useGallerySheet } from './useGallerySheet.js'
+
+// A gallery's item page, as viewer-layout's `RecordSheetView` spec
+// (inventory-app#2054): `useGallerySheet`'s field sheet, plus the blocks the
+// view reads through `spec.sourceDatabase`, `spec.notice`, `spec.museum` and
+// `spec.related.*` — the project chips, the Explore-partner notice, the
+// holding-museum link, and the related block's outside references,
+// cross-database links, dynasty popouts and timeline popout. The 37
+// galleries each carried this layer in their own `composables/gallery.js`,
+// the same code in all 37.
+//
+// What stays a gallery's own is read from its `dataset.config.js` through
+// `useSiteConfig()`, lazily, inside the functions the view calls at render
+// time — `dataset.config.js` is imported before `createViewer()` sets the
+// config, so a read at module level would only ever see the empty default:
+//
+//   * `projectColors`, project id → one of viewer-layout's `mwnf-chip--*`
+//     classes, for the source-database chip and an outside reference's chip;
+//   * `noticeProjects`, the projects whose sheets still carry legacy's
+//     Explore-partner notice.
+
+/**
+ * The gallery's item-page spec, over its data layer's `data` and its
+ * timeline layer's `timeline` (`useGalleryTimeline`).
+ *
+ * Reads `data.defaultLang`, `data.dynastyById`, `data.labelOf`,
+ * `data.partnerById`, `data.partnerRoute`, `data.translations`, what
+ * `useGallerySheet` reads, and `timeline.countryIdForCode`,
+ * `timeline.timelineEvents` (`countries`, `findEvents`).
+ */
+export function useGalleryItemDetail(data, timeline) {
+  const { defaultLang, dynastyById, labelOf, partnerById, partnerRoute, translations } = data
+  const { countryIdForCode, timelineEvents } = timeline
+  const { countries: timelineCountries, findEvents } = timelineEvents
+  const { itemSheet: platformSheet } = useGallerySheet(data)
+
+  const chipClass = (record) => useSiteConfig().projectColors?.[record.project_id] ?? null
+
+  function museumRoute(partnerId) {
+    const partner = partnerById.value.get(partnerId)
+    return partner ? partnerRoute(partner) : null
+  }
+
+  function dynastyTranslation(dynasty, language) {
+    return translations('dynasties', language)[dynasty.id] ?? translations('dynasties', defaultLang)[dynasty.id] ?? {}
+  }
+
+  // Legacy popped out a dynasty only when it had a history to show.
+  function itemDynasties(record, language) {
+    const records = (record.dynasty_ids ?? [])
+      .map((id) => dynastyById.value.get(id))
+      .filter((d) => d && dynastyTranslation(d, language).history)
+    return records.length ? { records, tr: (d) => dynastyTranslation(d, language) } : null
+  }
+
+  // The timeline popout, for the record's own date range: the gallery's own
+  // countries, events and search route.
+  function itemTimeline(record, ctx) {
+    const [from, to] = roundOutward(record.start_date, record.end_date)
+    if (from == null) return null
+    return {
+      heading: 'gallery.section.timeline',
+      countries: timelineCountries.value.map((c) => ({ value: c.value, label: c.label ?? ctx.t('timeline.form.allCountries') })),
+      defaultCountry: () => {
+        for (const { value: code } of timelineCountries.value) {
+          if (countryIdForCode(code) === record.country_id) return code
+        }
+        return 'all'
+      },
+      events: (country) => findEvents({ country, begin: from, end: to }),
+      range: [from, to],
+      era: (year) => eraLabel(year, ctx.t),
+      searchTo: (country, [begin, end]) => ({ name: 'timeline-results', query: { country, begin, end } }),
+    }
+  }
+
+  const itemDetail = {
+    ...platformSheet,
+    sourceDatabase: {
+      chipClass,
+    },
+    notice: {
+      show: (record) => (useSiteConfig().noticeProjects ?? []).includes(record.project_id),
+      label: 'gallery.item.explorePartnerNote',
+    },
+    museum: {
+      route: (partnerId) => museumRoute(partnerId),
+      label: (partnerId) => labelOf('partners', partnerId),
+    },
+    related: {
+      ...platformSheet.related,
+      title: 'gallery.related.title',
+      description: 'gallery.related.description',
+      notInPackageLabel: 'gallery.results.notInThisGallery',
+      // An outside `related_items` reference carries its `project_id`
+      // (inventory-app#1807), so it reads the same `projectColors` map.
+      outsideChip: chipClass,
+      artisticIntroductionLabel: 'gallery.nav.artisticIntroduction',
+      databaseLabel: 'gallery.search.relatedDatabase',
+      overallDatabase: { label: 'gallery.search.overallDatabase', linkLabel: 'gallery.nav.overallDatabase' },
+      onDisplayIn: { linkPendingLabel: 'gallery.item.linkPending' },
+      dynasties: (record, language) => itemDynasties(record, language),
+      timeline: itemTimeline,
+    },
+  }
+
+  return { itemDetail }
+}

package/src/dxa/gallery/useGalleryTimeline.js

@@ -1,4 +1,3 @@
-import { computed } from 'vue'
 import { dateRange, eraLabel, roundOutward, yearBucketsFromRange } from '../../catalogue/dates.js'
 import { useTimelineEvents } from '../../catalogue/timeline.js'
 import { PAGE_SIZE } from '../shared.js'
@@ -10,13 +9,13 @@ export { eraLabel, roundOutward }
  * `PAGE_SIZE`/`tile` its {@link import('./useGalleryCollection.js').useGalleryCollection}
  * already declared.
  *
- * Reads `data.timelines`, `data.countries`, `data.countryById`,
- * `data.labelOf`, `data.items`, `data.tr`, `data.loadTranslations`,
- * `data.defaultLang`. `config` carries nothing today.
+ * Reads `data.labelOf`, `data.items`, `data.tr`, `data.loadTranslations`,
+ * `data.defaultLang`, `data.countryIdForCode`, `data.countryLabel`.
+ * `config` carries nothing today.
  */
 export function useGalleryTimeline(data, collection, config = {}) {
   void config
-  const { timelines, countries, countryById, labelOf, items, tr, loadTranslations, defaultLang } = data
+  const { labelOf, items, tr, loadTranslations, defaultLang, countryIdForCode, countryLabel } = data
   const { tile } = collection
 
   // `TimelineResultsView` takes `tr` as a plain callback rather than an
@@ -28,96 +27,11 @@ export function useGalleryTimeline(data, collection, config = {}) {
 
   // The merge itself — the worldwide country chronology, `mwnf3.hcr`
   // combined with Sharing History's exhibition-2 rows the way legacy's
-  // `/v2/events` served it — is viewer-core's `useTimelineEvents`. What
-  // stays here is what is genuinely a gallery's own: the DXA legacy
-  // 2-letter country code (a gallery's Timeline URLs are keyed on it, not
-  // on the inventory id) and the two specs the composed views render from.
-  //
-  // 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' }
-
-  // `TimelineResultsView`'s own country control (`countries` from
-  // viewer-core) writes the inventory id, not the legacy code
-  // (`?country=dza`, not `?country=dz`); `countryIdForCode` used to answer
-  // nothing for one, silently matching every event. Built once, next to
-  // `LEGACY_TO_ISO`, rather than inside the function it is read from.
-  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
-    }
-  }
-
-  /** Display name for a country the chronology carries, keyed by inventory id. */
-  function countryLabel(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.
-   */
-  function countryIdForCode(code) {
-    if (!code || code === 'all') return null
-    // Already an id (the composed view's own control writes one): pass it
-    // through unchanged, before the legacy-code lookups below get a chance
-    // to find nothing and silently match every event.
-    if (countryIdSet.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
-  }
+  // `/v2/events` served it — is viewer-core's `useTimelineEvents`, and the
+  // DXA legacy 2-letter country code a gallery's Timeline URLs are keyed on
+  // is the data layer's (`countryIdForCode`, `countryLabel`). What stays
+  // here is what is genuinely a gallery's own: the two specs the composed
+  // views render from.
 
   /**
    * The one merge engine every Timeline page on a gallery shares —

package/src/dxa/index.js

@@ -26,9 +26,12 @@ export { useGalleryCollection } from './gallery/useGalleryCollection.js'
 export { useGalleryTimeline } from './gallery/useGalleryTimeline.js'
 export { useGalleryPartner } from './gallery/useGalleryPartner.js'
 export { useGallerySheet } from './gallery/useGallerySheet.js'
+export { useGalleryItemDetail } from './gallery/useGalleryItemDetail.js'
 
 export { useExhibitionData } from './exhibition/useExhibitionData.js'
 export { useExhibitionCollection } from './exhibition/useExhibitionCollection.js'
 export { useExhibitionTimeline } from './exhibition/useExhibitionTimeline.js'
 export { useExhibitionPartner } from './exhibition/useExhibitionPartner.js'
 export { useExhibitionSheet } from './exhibition/useExhibitionSheet.js'
+export { useExhibitionItemDetail } from './exhibition/useExhibitionItemDetail.js'
+export { buildThemePictures, romanFor, useExhibitionThemes } from './exhibition/useExhibitionThemes.js'