@museumwnf/viewer-core 1.14.0

package/src/catalogue/listQuery.js

@@ -0,0 +1,100 @@
+import { computed, reactive, watch } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+
+// The state of a list page lives in the URL, and the URL is what a visitor
+// shares, bookmarks and comes back to through history. Every results page of
+// every website therefore does the same four things: read the filters and the
+// page out of `route.query`, keep them in step when the route changes under
+// it, write them back when the visitor acts, and start again from page one
+// when a filter changes. Eleven views wrote those four things by hand before
+// this existed, each with its own idiom and its own small differences.
+//
+// The convention this encodes is rule R8 of the alignment pass: filters and
+// the page travel in the query, never in the path; `page` is dropped when it
+// is 1; a filter change is a new place in history (`push`), a page change
+// replaces the current one (`replace`), and either navigates on the route the
+// page is already on, by name, so no view writes a path.
+
+const PAGE = 'page'
+
+function firstValue(value) {
+  return Array.isArray(value) ? (value[0] ?? '') : value ?? ''
+}
+
+function pageOf(query) {
+  const parsed = Number.parseInt(firstValue(query[PAGE]), 10)
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 1
+}
+
+/**
+ * Filters and page bound to the route query.
+ *
+ * `keys` names the filters this page knows. `filters` is a reactive object
+ * with one string per key — bind a control to it, then `apply()` to navigate
+ * with what it holds (or `apply(patch)` to change some and navigate at once,
+ * for a control that navigates on change). `reset()` clears every filter and
+ * navigates. `goToPage(n)` changes only the page. `page` is the current page,
+ * read from the query. `active` says whether any filter is set.
+ *
+ * Query parameters the page does not own — `lang`, a parameter of another
+ * component — are carried across every navigation untouched.
+ */
+export function useListQuery({ keys = [], page = true } = {}) {
+  const route = useRoute()
+  const router = useRouter()
+
+  const filters = reactive(Object.fromEntries(keys.map((key) => [key, ''])))
+
+  function readFromRoute() {
+    for (const key of keys) filters[key] = String(firstValue(route.query[key]))
+  }
+  readFromRoute()
+  // The route changing under the page — back, forward, a link to the same
+  // page with other filters — is the URL speaking; the controls follow it.
+  watch(() => route.query, readFromRoute)
+
+  const current = computed(() => (page ? pageOf(route.query) : 1))
+  const active = computed(() => keys.some((key) => filters[key] !== ''))
+
+  function foreignQuery() {
+    const out = {}
+    for (const [key, value] of Object.entries(route.query)) {
+      if (!keys.includes(key) && key !== PAGE) out[key] = value
+    }
+    return out
+  }
+
+  function ownQuery() {
+    const out = {}
+    for (const key of keys) if (filters[key] !== '') out[key] = filters[key]
+    return out
+  }
+
+  function location(query) {
+    return { name: route.name, params: route.params, query }
+  }
+
+  /** Navigate with the filters as they are, or with `patch` applied first. Starts at page 1. */
+  function apply(patch = {}) {
+    for (const [key, value] of Object.entries(patch)) {
+      if (keys.includes(key)) filters[key] = value == null ? '' : String(value)
+    }
+    return router.push(location({ ...foreignQuery(), ...ownQuery() }))
+  }
+
+  /** Clear every filter and navigate. */
+  function reset() {
+    for (const key of keys) filters[key] = ''
+    return router.push(location(foreignQuery()))
+  }
+
+  /** Another page of the same results: the same place in history, so back leaves the list. */
+  function goToPage(n) {
+    const target = Math.max(1, Number.parseInt(n, 10) || 1)
+    const query = { ...foreignQuery(), ...ownQuery() }
+    if (target > 1) query[PAGE] = String(target)
+    return router.replace(location(query))
+  }
+
+  return { filters, page: current, active, apply, reset, goToPage }
+}

package/src/catalogue/pagination.js

@@ -0,0 +1,57 @@
+import { computed, toValue } from 'vue'
+
+// One page arithmetic for every list. Five implementations existed — this
+// package's own ListView, a block inlined into six standalone views, a
+// component copied into four DXA sites, and two idioms for the count — and
+// they disagreed on nothing but shape. This is the DXA shape, which answers
+// everything a page needs to render itself: where it is, how far it goes,
+// and which rows it holds.
+
+const DEFAULT_SIZE = 20
+
+/**
+ * `{ total, lastPage, currentPage, from, to, rows }` for one page of `list`.
+ * A page past the end clamps to the last one; a page below one is the first;
+ * `from`/`to` are 1-based and both 0 for an empty list. The size is the
+ * caller's: twenty on the standalone sites and nine on the DXA sites are
+ * both legacy facts, and neither is this function's to decide.
+ */
+export function paginate(list, page, size = DEFAULT_SIZE) {
+  const rows = list ?? []
+  const total = rows.length
+  const perPage = Math.max(1, Number(size) || DEFAULT_SIZE)
+  const lastPage = Math.max(1, Math.ceil(total / perPage))
+  const requested = Number.parseInt(page, 10)
+  const currentPage = Math.min(Math.max(1, Number.isFinite(requested) ? requested : 1), lastPage)
+  const start = (currentPage - 1) * perPage
+  return {
+    total,
+    lastPage,
+    currentPage,
+    from: total === 0 ? 0 : start + 1,
+    to: Math.min(start + perPage, total),
+    rows: rows.slice(start, start + perPage),
+  }
+}
+
+/**
+ * `paginate` over reactive sources: `list` and `page` may each be a ref, a
+ * computed, a getter or a plain value — a `useListQuery().page`, typically.
+ */
+export function usePagination(list, { page = 1, size = DEFAULT_SIZE } = {}) {
+  return computed(() => paginate(toValue(list), toValue(page), toValue(size)))
+}
+
+/**
+ * Chronological order by `key` (a record's `start_date`), undated records
+ * last — or first, with `undated: 'first'`. Stable: two records of the same
+ * year keep the order they arrived in. Returns a new array.
+ */
+export function sortChronological(list, { key = 'start_date', undated = 'last' } = {}) {
+  const missing = undated === 'first' ? -Infinity : Infinity
+  const year = (record) => {
+    const value = record?.[key]
+    return typeof value === 'number' && Number.isFinite(value) ? value : missing
+  }
+  return [...(list ?? [])].sort((a, b) => year(a) - year(b))
+}

package/src/catalogue/searchLanguage.js

@@ -0,0 +1,32 @@
+import { computed, ref, watch } from 'vue'
+import { useDataPackage } from '../composables/useDataPackage.js'
+
+/**
+ * The search-language rule: a sorted list of languages the entity's
+ * translations exist in, and a watcher that loads them when the selection
+ * changes. Three Database pages carry this watch locally, reading three
+ * different entity names.
+ */
+export function useSearchLanguage(entity) {
+  const { availableLanguages, loadTranslations } = useDataPackage()
+
+  // The languages the entity actually carries translations in, sorted.
+  const languages = computed(() => {
+    const available = availableLanguages(entity)
+    return available.slice().sort()
+  })
+
+  // The user's current selection.
+  const language = ref('')
+
+  // Load translations when the selection changes; the watch runs immediately
+  // so the reference language (English, the index language) is always there.
+  watch(() => language.value, (lang) => {
+    if (lang) loadTranslations(entity, lang)
+  }, { immediate: true })
+
+  return {
+    languages,
+    language,
+  }
+}

package/src/catalogue/timeline.js

@@ -0,0 +1,220 @@
+import { computed } from 'vue'
+import { entityRef } from '../composables/useEntities.js'
+import { eraLabel, yearBucketsFromRange } from './dates.js'
+
+// The country chronology (`hcr` in legacy) is one merged, year-ordered list
+// per country, served by legacy `/v2/events` and reproduced identically on
+// every gallery and standalone site. An exhibition can instead carry its own
+// narrative chronology (`source: 'thg_local'` — legacy's `/thg/timeline`),
+// which has no country of its own and is never interleaved with the merge.
+// Sharing History's Timeline additionally splits the merge by the exhibition
+// each event belongs to (`collection_id` on its timeline row, `null` for the
+// Permanent Collection). Every one of the seven websites' Timeline pages is
+// one of these three axes over the same event shape — this is the one place
+// that shape is read.
+//
+// The event overlap rule was triplicated verbatim (islamicart, baroqueart,
+// sharinghistory) and mirrors legacy `class.hcr.inc.php`'s SQL; carpets and
+// water-in-islam wrote a related but distinct copy for the DXA sites. Both
+// are ported here rather than merged into a fourth variant, because the two
+// already ship identical answers on the cases that matter (see the tests):
+// the only real divergence was which of the three label rules a site reached
+// for, which is now one function trying all three in the order the data
+// disambiguates them.
+//
+// What stays out, by design: the DXA legacy 2-letter country code
+// (`legacyCodeOf`/`nameFor` in carpets and water-in-islam) — parsing
+// `backward_compatibility` and falling back to `Intl.DisplayNames` is a
+// concern of the sites still keying their Timeline URLs on that code, not of
+// the merge itself. Those sites pass `countryIdForCode` to translate their
+// code back to the id this module filters on.
+
+/** `year_to === 0` mirrors the legacy convention for an open-ended period. */
+export function effectiveYearTo(event) {
+  return event?.year_to && event.year_to !== 0 ? event.year_to : null
+}
+
+/**
+ * Whether `event` falls in `[begin, end]`, either bound optional — legacy's
+ * `class.hcr.inc.php` rule: an event with a known end overlaps once that end
+ * is past `begin` and its start is before `end`; an open-ended event (no
+ * known end) overlaps on its start alone. An event with no `year_from` at
+ * all never overlaps a bounded search — there is nothing to compare — but
+ * still matches a search with no bound, the same as every dated event does.
+ */
+export function overlapsRange(event, begin, end) {
+  const yf = event?.year_from
+  const yt = effectiveYearTo(event)
+  if (begin == null && end == null) return true
+  if (!Number.isFinite(yf)) return false
+  if (begin != null && end != null) {
+    return yt !== null ? yt > begin && yf < end : yf > begin && yf < end
+  }
+  if (begin != null) return yt !== null ? yt > begin : yf > begin
+  return yf <= end
+}
+
+/**
+ * The label under an event, trying the three rules the sites share in the
+ * order the data disambiguates them: a curated description pair
+ * (`date_from_description`/`date_to_description`, for an event whose date
+ * is imprecise in a way a bare year cannot say — every package's named event
+ * carries a date description too, so the title is not a date), a narrative
+ * chronology's own period name (`text.name`, a sort key, only tried when an
+ * event has no date description at all), and failing both, the derived year
+ * range through `eraLabel` — the one reached for by the worldwide country
+ * merge, which has neither.
+ */
+export function eventDateLabel(event, text, t) {
+  if (text?.date_from_description) {
+    // Legacy printed the pair only when the two differ; the era branch
+    // collapses an equal year_from/year_to the same way. Trim before
+    // comparing so that whitespace doesn't bloat the display.
+    if (text.date_to_description?.trim() === text.date_from_description.trim()) {
+      return text.date_from_description
+    }
+    return text.date_to_description
+      ? `${text.date_from_description} – ${text.date_to_description}`
+      : text.date_from_description
+  }
+  if (text?.name) return text.name
+  if (!Number.isFinite(event?.year_from)) return ''
+  const from = eraLabel(event.year_from, t)
+  const yt = effectiveYearTo(event)
+  return yt !== null ? `${from} – ${eraLabel(yt, t)}` : `${from} –`
+}
+
+/**
+ * The engine of a Timeline results page, one implementation for the three
+ * axes legacy split across separate endpoints:
+ *
+ * - `'country'` — the worldwide country merge (galleries, and the standalone
+ *   sites that offer only this axis);
+ * - `'local'` — an exhibition's own narrative chronology in place of the
+ *   merge (the `thg_local` timeline row), no country picker;
+ * - `'collection'` — the merge again, plus filtering by which exhibition an
+ *   event's timeline is bound to (`null` = the Permanent Collection), for
+ *   Sharing History's second axis.
+ *
+ * `countryLabel(countryId)` names a country for the picker and is the
+ * site's own — a country reads as its name, which this module has no way to
+ * know. `countryIdForCode`, if given, resolves a `findEvents({ country })`
+ * value through the site's own legacy-code table before filtering; omit it
+ * and `country` is already the id. `tr(id)` returns an event's translated
+ * fields already resolved for entity and language — the site's own `tr`,
+ * bound the way every data composable already binds it. `timelinesEntity`
+ * / `eventsEntity` name the data package files, for a site that calls its
+ * own something else.
+ */
+export function useTimelineEvents({
+  scope = 'country',
+  countryLabel,
+  countryIdForCode,
+  tr,
+  timelinesEntity = 'timelines',
+  eventsEntity = 'timeline_events',
+} = {}) {
+  const timelines = entityRef(timelinesEntity)
+  const events = entityRef(eventsEntity)
+
+  // The narrative chronology has no country of its own, so it must be kept
+  // out of the merge by `source` rather than by the country filter — on "all
+  // countries" it would otherwise interleave into the worldwide list.
+  const localTimeline = computed(
+    () => (timelines.value ?? []).find((row) => row.source === 'thg_local') ?? null,
+  )
+
+  const timelineById = computed(() => new Map((timelines.value ?? []).map((row) => [row.id, row])))
+
+  /** The events this scope works over — one chronology, never both. */
+  const eventPool = computed(() => {
+    const all = events.value ?? []
+    const local = localTimeline.value
+    if (scope === 'local') return local ? all.filter((event) => event.timeline_id === local.id) : []
+    return local ? all.filter((event) => event.timeline_id !== local.id) : all
+  })
+
+  const hasTimeline = computed(() => eventPool.value.length > 0)
+  const usesLocalTimeline = computed(() => scope === 'local' && Boolean(localTimeline.value))
+
+  /**
+   * Countries that actually have a chronology, alphabetized by label, with
+   * an "all" marker first — the marker carries no label of its own, so the
+   * picker renders it through its own catalogue entry. No picker at all for
+   * `'local'`: legacy hides the country select once the section is the
+   * exhibition's own chronology, because there is nothing to filter by.
+   */
+  const countries = computed(() => {
+    if (scope === 'local') return []
+    const seen = new Map()
+    for (const row of timelines.value ?? []) {
+      if (!row.country_id || seen.has(row.country_id)) continue
+      seen.set(row.country_id, {
+        value: row.country_id,
+        label: countryLabel ? countryLabel(row.country_id) : row.country_id,
+      })
+    }
+    const rows = [...seen.values()].sort((a, b) => String(a.label).localeCompare(String(b.label)))
+    return [{ value: 'all', label: null }, ...rows]
+  })
+
+  /** Every event year present in this scope, as the year picker's source range. */
+  const yearRange = computed(() => {
+    const years = eventPool.value
+      .map((event) => event.year_from)
+      .filter((value) => Number.isFinite(value) && value !== 0)
+    if (!years.length) return [null, null]
+    return [Math.min(...years), Math.max(...years)]
+  })
+
+  /** The legacy era buckets over this scope's year range. */
+  function yearBuckets(t) {
+    const [min, max] = yearRange.value
+    return yearBucketsFromRange(min, max, t)
+  }
+
+  function resolveCountryId(country) {
+    if (country == null || country === 'all') return null
+    return countryIdForCode ? countryIdForCode(country) : country
+  }
+
+  // `null` is Sharing History's Permanent Collection sentinel — a timeline
+  // bound to no exhibition — so it must be told apart from "no filter",
+  // which `collection: undefined` spells instead.
+  function matchesCollection(event, collection) {
+    const collectionId = timelineById.value.get(event.timeline_id)?.collection_id ?? null
+    return collection === null ? collectionId === null : collectionId === collection
+  }
+
+  /**
+   * Legacy's `/events?ic[]=&ya=&yo=` (and Sharing History's exhibition
+   * filter alongside it) — this scope's events in `[begin, end]`, for the
+   * given country and/or collection, chronological. `display_order` breaks a
+   * tie on `year_from`, the order the exhibition itself gave two events of
+   * the same year; an event with no year at all has no place in that order
+   * and sorts after every dated one.
+   */
+  function findEvents({ country, collection, begin, end } = {}) {
+    const countryId = resolveCountryId(country)
+    const from = begin === '' || begin == null ? null : Number(begin)
+    const to = end === '' || end == null ? null : Number(end)
+
+    return eventPool.value
+      .filter((event) => {
+        // A narrative chronology's events carry no country_id at all — the
+        // filter has nothing to apply itself to, the same reason `countries`
+        // renders no picker for this scope.
+        if (scope !== 'local' && countryId && event.country_id !== countryId) return false
+        if (collection !== undefined && !matchesCollection(event, collection)) return false
+        return overlapsRange(event, from, to)
+      })
+      .map((event) => ({ ...event, text: tr ? tr(event.id) : {} }))
+      .sort((a, b) => {
+        const ya = Number.isFinite(a.year_from) ? a.year_from : Infinity
+        const yb = Number.isFinite(b.year_from) ? b.year_from : Infinity
+        return ya - yb || (a.display_order ?? 0) - (b.display_order ?? 0)
+      })
+  }
+
+  return { countries, yearRange, yearBuckets, hasTimeline, usesLocalTimeline, findEvents }
+}

package/src/composables/useCatalogueData.js

@@ -0,0 +1,141 @@
+import { computed } from 'vue'
+import { useDataPackage } from './useDataPackage.js'
+import { byId as coreById, entityRef } from './useEntities.js'
+import { md as coreMd, mdInline as coreMdInline, mdStrip as coreMdStrip } from '../i18n/markdown.js'
+import { glossaryEntries } from '../record/recordSheet.js'
+
+// The wrapper half of seven sites' data composables (2,376 lines across
+// them), written once. Every one of them re-wrapped the same `tr`, the same
+// memoised `loadEnglish`, the same one-shape label helper
+// (`mdStrip(tr(entity, id).name ?? record.internal_name ?? id)`), and the
+// same `md`/`mdInline`/`mdStrip` re-export, around whichever entities and
+// visibility rules were its own — a per-build language filter, a hidden-
+// partner rule, `display_status` — coded rather than declared. This is that
+// wrapper. What survives in a site's own composable is what genuinely
+// differs: routes, legacy key mappings, chrome images, sibling lists.
+//
+// Called once, at the top of a site's data composable module, and its
+// return value re-exported from there — the way `entityRef`/`byId` are
+// already read at module scope, so importing the module loads nothing and a
+// page pays only for the entity it declares. `entity`/`index` read the same
+// shared `entityRef`/`byId` this file does, so a second call would only
+// duplicate the memoisation `loadEnglish` and the glossary binding carry —
+// one instance per site, not one per component.
+const BASE_LANGUAGE = 'en'
+
+// A term's spellings and definition in one language, falling back to
+// English, then to the term's own headword — the same row shape
+// `useRecordSheet`'s `termRow` builds, but for the whole glossary in
+// `defaultLanguage` rather than one record's `glossary_ids` in the record's
+// own language, which is why it is not reused: a catalogue list or a label
+// is always shown in `defaultLanguage`, a record sheet's text is not.
+function glossaryRows(language, translations) {
+  const rows = translations('glossary', language)
+  const fallback = translations('glossary', BASE_LANGUAGE)
+  const terms = []
+  for (const term of entityRef('glossary').value ?? []) {
+    const t = rows[term.id] ?? fallback[term.id] ?? {}
+    const spellings = (t.spellings ?? []).map((s) => String(s).trim()).filter(Boolean)
+    const word = term.word ?? spellings[0] ?? ''
+    if (!word && spellings.length === 0) continue
+    terms.push({ id: term.id, word, definition: t.definition ?? '', spellings: spellings.length ? spellings : [word] })
+  }
+  return terms
+}
+
+/**
+ * The wrapper half of a website's data composable: `tr`, `md`/`mdInline`/
+ * `mdStrip` bound to the site's glossary, `loadEnglish`, `labelOf`, the
+ * visible form of an entity and its index, and the package re-exports.
+ *
+ * `eager` names the entities `loadEnglish` loads — every entity the package
+ * carries by default. `defaultLanguage` is the language `tr`, the labels and
+ * the glossary binding read (`'en'` for every site so far). `visible` names,
+ * per entity, the predicate `entity()`/`index()` apply — a per-build
+ * language filter, a hidden-partner rule, a display-status check are all
+ * "which records this build shows", declared here once instead of coded
+ * into every page that lists that entity. `glossary` turns off the default
+ * binding on `md`/`mdInline` (a caller may still pass its own `glossary` to
+ * either, on or off).
+ */
+export function useCatalogueData({ eager, defaultLanguage = BASE_LANGUAGE, visible = {}, glossary = true } = {}) {
+  const pkg = useDataPackage()
+  const { availableLanguages, loadTranslations, translations } = pkg
+  const eagerEntities = eager ?? pkg.entityNames
+
+  /** One record's translated fields, falling back to `defaultLanguage` then `{}`. */
+  function tr(entity, id, lang = defaultLanguage) {
+    return pkg.tr(entity, id, lang, defaultLanguage)
+  }
+
+  const defaultGlossary = computed(() =>
+    glossary ? glossaryEntries(glossaryRows(defaultLanguage, translations)) : [],
+  )
+
+  // A caller's own `glossary` — a record's own terms, not every term in the
+  // package — always wins, whether the default binding is on or off; `md`
+  // and `mdInline` differ only in which core renderer they wrap, `mdStrip`
+  // has nothing to bind, since plain text carries no highlighting.
+  function bindGlossary(renderer) {
+    return (text, opts = {}) =>
+      renderer(text, { ...opts, glossary: 'glossary' in opts ? opts.glossary : defaultGlossary.value })
+  }
+  const md = bindGlossary(coreMd)
+  const mdInline = bindGlossary(coreMdInline)
+  const mdStrip = coreMdStrip
+
+  /** `mdStrip(tr(entity, id).name ?? record[fallback] ?? id)` — the one label shape every site wrote. */
+  function labelOf(entity, id, { fallback = 'internal_name' } = {}) {
+    if (!id) return ''
+    const name = tr(entity, id).name
+    if (name) return mdStrip(name)
+    const record = coreById(entity).value.get(id)
+    return mdStrip(record?.[fallback] ?? id)
+  }
+
+  let englishReady = null
+  /** Loads `defaultLanguage` for every entity in `eager`, once. */
+  function loadEnglish() {
+    if (!englishReady) {
+      englishReady = Promise.all(eagerEntities.map((name) => loadTranslations(name, defaultLanguage)))
+    }
+    return englishReady
+  }
+
+  // Cached the way `byId` is: a site reads `entity('items')`/`index('items')`
+  // from more than one place, and each should see the same ref rather than
+  // a fresh filter pass and a fresh Map per call.
+  const entityCache = new Map()
+  /** `entityRef(name)`'s records, narrowed by `visible[name]` when one is declared; `null` until loaded. */
+  function entity(name) {
+    let ref = entityCache.get(name)
+    if (!ref) {
+      const source = entityRef(name)
+      const predicate = visible[name]
+      ref = computed(() => {
+        if (source.value === null) return null
+        return predicate ? source.value.filter(predicate) : source.value
+      })
+      entityCache.set(name, ref)
+    }
+    return ref
+  }
+
+  const indexCache = new Map()
+  /** A `Map` of `entity(name)`'s records by `key` — the visible ones, unlike `byId`. */
+  function index(name, key = 'id') {
+    const cacheKey = `${name}.${key}`
+    let ref = indexCache.get(cacheKey)
+    if (!ref) {
+      const list = entity(name)
+      ref = computed(() => new Map((list.value ?? []).map((record) => [record[key], record])))
+      indexCache.set(cacheKey, ref)
+    }
+    return ref
+  }
+
+  return {
+    tr, md, mdInline, mdStrip, loadEnglish, labelOf, entity, index,
+    availableLanguages, loadTranslations, translations,
+  }
+}

package/src/composables/useDataPackage.js

@@ -0,0 +1,98 @@
+import { ref } from 'vue'
+
+// package.json is npm metadata, not an entity — exclude it from the glob.
+const entityModules = import.meta.glob(['@inventory-data/*.json', '!**/package.json'])
+const manifestModules = import.meta.glob('@inventory-data/manifest.json', { eager: true })
+
+// One file per entity per language; a file is simply absent when that entity
+// has no translation in that language. Left lazy (unlike entityModules'
+// eager-in-spirit-but-actually-per-call loaders, this one also needs a
+// reactive cache — see below) so a build only bundles what a page visit
+// actually requests, not every language of every entity.
+const translationModules = import.meta.glob('@inventory-data/translations/*.json')
+
+const manifest = Object.values(manifestModules)[0]?.default ?? {}
+
+const entityLoaders = {}
+for (const [path, load] of Object.entries(entityModules)) {
+  const name = path.split('/').pop().replace(/\.json$/, '')
+  if (name !== 'manifest') {
+    entityLoaders[name] = load
+  }
+}
+
+function translationLoader(entity, lang) {
+  const suffix = `/translations/${entity}.${lang}.json`
+  const path = Object.keys(translationModules).find((k) => k.endsWith(suffix))
+  return path ? translationModules[path] : null
+}
+
+// `${entity}.${lang}` → record map, or `{}` once a miss has been resolved.
+// A plain `await import()` would already be deduped by the module system;
+// this cache exists so a component reading through `translations`/`tr` -
+// synchronous, not awaited - re-renders once a lazy `loadTranslations` call
+// elsewhere resolves.
+const translationCache = ref({})
+
+export function useDataPackage() {
+  return {
+    manifest,
+    languages: manifest.languages ?? ['en'],
+    entityNames: Object.keys(entityLoaders).sort(),
+    async loadEntity(name) {
+      const load = entityLoaders[name]
+      if (!load) {
+        throw new Error(`Unknown entity "${name}" in the data package`)
+      }
+      const module = await load()
+      return module.default ?? module
+    },
+
+    /** Languages `translations/<entity>.<lang>.json` actually exists for. */
+    availableLanguages(entity) {
+      const prefix = `/translations/${entity}.`
+      return Object.keys(translationModules)
+        .filter((k) => k.includes(prefix))
+        .map((k) => k.slice(k.lastIndexOf(prefix) + prefix.length, -'.json'.length))
+    },
+
+    /**
+     * Lazy-loads `translations/<entity>.<lang>.json` (a map of record id to
+     * that record's translated fields); `{}` when the file does not exist.
+     * Cached, so calling it again for the same pair is free.
+     */
+    async loadTranslations(entity, lang) {
+      const key = `${entity}.${lang}`
+      if (translationCache.value[key]) return translationCache.value[key]
+      const load = translationLoader(entity, lang)
+      let data = {}
+      if (load) {
+        try {
+          data = (await load()).default ?? {}
+        } catch {
+          data = {}
+        }
+      }
+      translationCache.value = { ...translationCache.value, [key]: data }
+      return data
+    },
+
+    /** Already-loaded translations for one entity/lang; `{}` if not loaded yet (or absent). */
+    translations(entity, lang) {
+      return translationCache.value[`${entity}.${lang}`] ?? {}
+    },
+
+    /**
+     * One record's translated fields, falling back to `fallbackLang` (default
+     * `'en'`) then to `{}`. Reads only what is already loaded — call
+     * `loadTranslations` first for each language a page may need.
+     */
+    tr(entity, id, lang, fallbackLang = 'en') {
+      return (
+        translationCache.value[`${entity}.${lang}`]?.[id] ??
+        translationCache.value[`${entity}.${fallbackLang}`]?.[id] ??
+        {}
+      )
+    },
+  }
+}