@museumwnf/viewer-core 2.3.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,9 +560,9 @@ 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`) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@museumwnf/viewer-core",
-  "version": "2.3.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

@@ -25,14 +25,15 @@ import { useExhibitionSheet } from './useExhibitionSheet.js'
  * Reads `data.defaultLang`, `data.dynastyById`, `data.isExploreRecord`,
  * `data.isHiddenPartner`, `data.labelOf`, `data.partnerById`,
  * `data.partnerRoute`, `data.translations`, what `useExhibitionSheet` reads,
- * and `timeline.countryIdForCode`, `timeline.findEvents`,
- * `timeline.hasTimeline`, `timeline.timelineCountries`, `timeline.timelineSpec`.
+ * 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, findEvents, hasTimeline, timelineCountries, timelineSpec } = timeline
+  const { countryIdForCode, hasTimeline, timelineEvents, timelineSpec } = timeline
+  const { countries: timelineCountries, findEvents } = timelineEvents
   const { itemSheet: platformSheet } = useExhibitionSheet(data)
 
   function chipClass(record) {
@@ -50,11 +51,11 @@ export function useExhibitionItemDetail(data, timeline) {
       .filter((d) => d && dynastyTr(d, language).history)
   }
 
-  // The country the "Timeline for this item" popout opens on: the legacy
-  // two-letter code whose id is the record's own country.
-  function countryCodeOf(countryId) {
-    for (const [code] of timelineCountries.value) {
-      if (countryIdForCode(code) === countryId) return code
+  // 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
   }
@@ -63,9 +64,9 @@ export function useExhibitionItemDetail(data, timeline) {
   // 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(countryCode, range) {
+  function periodSearch(country, range) {
     const keys = new Set((timelineSpec.value?.controls ?? []).map((control) => control.key))
-    const query = { country: countryCode, begin: range[0], end: range[1] }
+    const query = { country, begin: range[0], end: range[1] }
     return { name: 'timeline-results', query: Object.fromEntries(Object.entries(query).filter(([key]) => keys.has(key))) }
   }
 
@@ -115,9 +116,9 @@ export function useExhibitionItemDetail(data, timeline) {
         if (range[0] == null) return null
         return {
           heading: 'exhibition.section.timeline',
-          countries: timelineCountries.value.map(([value, label]) => ({ value, label })),
-          defaultCountry: () => countryCodeOf(record.country_id) ?? 'all',
-          events: (countryCode) => findEvents({ countryCode, start: range[0], end: range[1] }),
+          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,

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/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 —