@museumwnf/viewer-core 1.14.0

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@museumwnf/viewer-core",
+  "version": "1.14.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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/metanull/viewer-core.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "src"
+  ],
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./i18n": "./src/i18n/index.js",
+    "./legacy": "./src/legacy/index.js",
+    "./testing": "./src/testing/index.js",
+    "./vite": "./src/vite.js",
+    "./styles/base.css": "./src/styles/base.css"
+  },
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "scripts": {
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "marked": "^18.0.11"
+  },
+  "peerDependencies": {
+    "vue": "^3.5.0",
+    "vue-router": "^4.5.0 || ^5.0.0"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^6.0.8",
+    "@vue/test-utils": "^2.4.11",
+    "jsdom": "^30.0.1",
+    "vite": "^8.2.2",
+    "vitest": "^4.1.11",
+    "vue": "^3.5.0",
+    "vue-router": "^5.0.0"
+  }
+}

package/src/AppRoot.vue

@@ -0,0 +1,58 @@
+<script setup>
+import { computed, inject, ref } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import { useI18n } from './i18n/index.js'
+import { negotiateLanguage } from './i18n/language.js'
+import { VIEWER_CONFIG } from './injectionKeys.js'
+
+const config = inject(VIEWER_CONFIG, {})
+const { locale } = useI18n()
+const route = useRoute()
+const router = useRouter()
+
+// The shell receives the resolved language list, everything the website put in
+// config.navigation, and the current locale — in that order, so `language`
+// always reflects the live locale.
+const shellProps = computed(() => ({
+  languages: config.languages,
+  ...(config.navigation ?? {}),
+  language: locale.value,
+}))
+
+// The shell is the website's own component, so what it emits is checked here
+// rather than trusted: the active language is always one the website offers.
+function setLanguage(language) {
+  locale.value = negotiateLanguage(config.languages, { requested: language })
+}
+
+// Until the first navigation has resolved — which includes loading the
+// entities the route declares — there is no view to show, and the page says
+// so rather than staying blank.
+const navigating = ref(true)
+router.beforeEach(() => {
+  navigating.value = true
+})
+router.afterEach(() => {
+  navigating.value = false
+})
+router.onError(() => {
+  navigating.value = false
+})
+const loading = computed(() => navigating.value && route.matched.length === 0)
+</script>
+
+<template>
+  <component
+    :is="config.shell"
+    v-if="config.shell"
+    v-bind="shellProps"
+    @update:language="setLanguage"
+  >
+    <p v-if="loading" class="vc-loading">{{ $t('core.status.loading') }}</p>
+    <router-view v-else />
+  </component>
+  <template v-else>
+    <p v-if="loading" class="vc-loading">{{ $t('core.status.loading') }}</p>
+    <router-view v-else />
+  </template>
+</template>

package/src/catalogue/dates.js

@@ -0,0 +1,209 @@
+// Two date rules, both legacy, never merged.
+//
+// The standalone sites (Islamic Art, Baroque Art, Sharing History) test
+// overlap, tolerating a record that carries one date only: "from 800" keeps
+// a record whose end is at or after 800, or — with no end — whose start is.
+// The DXA sites (the galleries and exhibitions) test containment, the
+// predicate of legacy's `Objects.blade.php`: `na <= start_date` and
+// `nz >= coalesce(end_date, start_date)`, so an undated record is out the
+// moment a bound is set. They give different answers on the same data, and
+// each website has published its answer for years. A site names its rule
+// once, in its catalogue spec; this file only makes sure the two cannot be
+// confused for one.
+
+const number = (value) => {
+  if (value === '' || value == null) return null
+  const n = Number(value)
+  return Number.isFinite(n) ? n : null
+}
+
+const year = (record, field) => {
+  const value = record?.[field]
+  return typeof value === 'number' && Number.isFinite(value) ? value : null
+}
+
+/**
+ * Whether `record` falls in `[begin, end]` under `mode`: `'overlap'` (the
+ * standalone rule) or `'contain'` (the DXA rule). A bound that is empty or
+ * absent is not applied. `fields` names the record's start and end properties.
+ */
+export function inDateRange(record, { begin, end, mode = 'overlap', fields = {} } = {}) {
+  const from = number(begin)
+  const to = number(end)
+  const start = year(record, fields.start ?? 'start_date')
+  const last = year(record, fields.end ?? 'end_date')
+
+  if (mode === 'contain') {
+    if (from != null && (start == null || from > start)) return false
+    if (to != null) {
+      const final = last ?? start
+      if (final == null || to < final) return false
+    }
+    return true
+  }
+  if (mode !== 'overlap') throw new Error(`Unknown date mode "${mode}": use "overlap" or "contain"`)
+
+  if (from != null) {
+    if (last != null) {
+      if (last < from) return false
+    } else if (start != null && start < from) return false
+  }
+  if (to != null) {
+    if (start != null) {
+      if (start > to) return false
+    } else if (last != null && last > to) return false
+  }
+  return true
+}
+
+/** The records of `list` that `inDateRange` keeps. */
+export function dateRange(list, options = {}) {
+  return (list ?? []).filter((record) => inDateRange(record, options))
+}
+
+// ── Year buckets ───────────────────────────────────────────────────────────
+//
+// A verbatim port of `loadYears` in the legacy DXA client's collection.js
+// mixin, carried here from four identical copies. The API returned only a
+// min and a max; the client built the era buckets itself, with coarser steps
+// the further back you go (500 → 250 → 100 → 50), an explicit "Before 1000
+// BC" bucket, and an "After …" label when the final step is short. The
+// algorithm is reproduced rather than improved because its values end up in
+// shareable URLs, and a nicer bucket is a broken link.
+
+const nextMultiple = (n, m) => Math.ceil(n / m) * m
+const previousMultiple = (n, m) => Math.floor(n / m) * m
+
+function pushIncrements(from, maxRounded, incrementMax, increment, array) {
+  for (let i = from; i <= incrementMax; i += increment) {
+    if (i > maxRounded) return
+    array.push(i)
+  }
+}
+
+/**
+ * The era buckets between `min` and `max`, as `[{ value, label }]`. The era
+ * words on the labels are texts (`catalogue.era.bc`, `.ad`, `.before`,
+ * `.after`) and the years are not, which is why `t` comes in from the caller
+ * and the two are joined here rather than written into an entry with a hole
+ * in it.
+ */
+export function yearBucketsFromRange(min, max, t) {
+  if (!Number.isFinite(min) || !Number.isFinite(max)) return []
+
+  const increments = [500, 250, 100, 50]
+  let smallestIncrement
+  const array = [min]
+  let minRounded, maxRounded
+
+  if (max >= 1800) maxRounded = previousMultiple(max, increments[3])
+  else if (max >= 1000) maxRounded = previousMultiple(max, increments[2])
+  else if (max >= 0) maxRounded = previousMultiple(max, increments[1])
+  else maxRounded = previousMultiple(max, increments[0])
+
+  if (min <= 0) minRounded = nextMultiple(min, increments[0])
+  else if (min <= 1000) minRounded = nextMultiple(min, increments[1])
+  else if (min <= 1800) minRounded = nextMultiple(min, increments[2])
+  else minRounded = nextMultiple(min, increments[3])
+
+  let guard = 0
+  do {
+    if (minRounded < 0) {
+      pushIncrements(minRounded, maxRounded, 0, increments[0], array)
+      smallestIncrement = increments[0]
+    } else if (minRounded < 1000) {
+      pushIncrements(minRounded, maxRounded, 1000, increments[1], array)
+      smallestIncrement = increments[1]
+    } else if (minRounded < 1800) {
+      pushIncrements(minRounded, maxRounded, 1800, increments[2], array)
+      smallestIncrement = increments[2]
+    } else {
+      pushIncrements(minRounded, maxRounded, maxRounded, increments[3], array)
+      smallestIncrement = increments[3]
+    }
+    const last = array[array.length - 1]
+    // The legacy loop relies on the array growing; if a step adds nothing it
+    // would spin forever. Legacy never hit that because its data always did.
+    if (last === minRounded && guard++ > 0) break
+    minRounded = last
+  } while (array[array.length - 1] < maxRounded && guard++ < 64)
+
+  array.push(max)
+  const unique = [...new Set(array)]
+
+  const labelled = []
+  for (const value of unique) {
+    if (value < 0) labelled.push({ value, label: `${Math.abs(value)} ${t('catalogue.era.bc')}` })
+    else if (value > 0) labelled.push({ value, label: `${value} ${t('catalogue.era.ad')}` })
+  }
+  if (!labelled.length) return []
+
+  let display = labelled
+  if (labelled[0].value < -1000) {
+    display = labelled.filter(({ value }) => value >= -1000)
+    display.unshift({ value: min, label: `${t('catalogue.era.before')} 1000 ${t('catalogue.era.bc')}` })
+  }
+
+  if (display.length > 1) {
+    const lastGap = display[display.length - 1].value - display[display.length - 2].value
+    if (lastGap < smallestIncrement) {
+      const previous = display[display.length - 2]
+      display[display.length - 1] = {
+        value: display[display.length - 1].value,
+        label: `${t('catalogue.era.after')} ${previous.label}`,
+      }
+    }
+  }
+  return display
+}
+
+/** The buckets spanning the dates of `records` (`start_date` to `end_date ?? start_date`). */
+export function yearBuckets(records, t, { fields = {} } = {}) {
+  const startField = fields.start ?? 'start_date'
+  const endField = fields.end ?? 'end_date'
+  const starts = []
+  const ends = []
+  for (const record of records ?? []) {
+    const start = year(record, startField)
+    const end = year(record, endField) ?? start
+    if (start != null) starts.push(start)
+    if (end != null) ends.push(end)
+  }
+  if (!starts.length || !ends.length) return []
+  return yearBucketsFromRange(Math.min(...starts), Math.max(...ends), t)
+}
+
+/**
+ * "1193 AD" / "502 BC" — legacy's era suffix rule, for a year on its own.
+ * Nothing for a year that is missing or zero.
+ */
+export function eraLabel(year, t) {
+  if (!Number.isFinite(year) || year === 0) return ''
+  return year < 0 ? `${Math.abs(year)} ${t('catalogue.era.bc')}` : `${year} ${t('catalogue.era.ad')}`
+}
+
+/**
+ * A record's dates rounded outward to the century, the window legacy's
+ * "Timeline for this item" opens, so a single-year object still lands on a
+ * readable stretch of chronology. `[from, to]`, either null when unknown.
+ */
+export function roundOutward(start, end) {
+  const from = Number.isFinite(start) ? Math.floor(start / 100) * 100 : null
+  const last = Number.isFinite(end) ? end : start
+  const to = Number.isFinite(last) ? Math.ceil(last / 100) * 100 : null
+  return [from, to]
+}
+
+/**
+ * The century boundaries that three Database forms build locally, reproducing
+ * legacy `database.php:88–124`. The asymmetry between the two lists is preserved.
+ * The default range (501–2000) is the same as the legacy form's initial state.
+ */
+export function centuryPresets({ from = 501, to = 2000 } = {}) {
+  const fromOptions = Array.from({ length: 16 }, (_, i) => 501 + i * 100)
+  const toOptions = Array.from({ length: 15 }, (_, i) => 600 + i * 100)
+  return {
+    from: fromOptions,
+    to: toOptions,
+  }
+}

package/src/catalogue/facets.js

@@ -0,0 +1,61 @@
+import { computed, toValue } from 'vue'
+
+// The options a filter offers are the values the records in front of it
+// actually carry, labelled, sorted, and nothing else: a country no item is
+// from is not offered. Every results page derives that from its records —
+// the standalone sites copied the derivation into the entrance and the
+// results view of each site, the DXA sites wrote it over tags — and the one
+// real difference between them is which records they pass: all of them
+// (standalone), or the ones that survive the current filters (DXA, where
+// picking a country shrinks the type list). Both are legacy behaviours, and
+// both stay the caller's choice: this reads whatever records it is handed.
+
+const compareLabels = (a, b) => a.label.localeCompare(b.label)
+
+function valuesOf(record, spec) {
+  if (typeof spec.values === 'function') return [spec.values(record)].flat()
+  const raw = record?.[spec.field]
+  return Array.isArray(raw) ? raw : [raw]
+}
+
+function capitalize(text) {
+  const label = String(text ?? '')
+  return label.charAt(0).toUpperCase() + label.slice(1)
+}
+
+/**
+ * `{ [facet]: [{ value, label }] }` from `records`, one entry per facet of
+ * `spec`. A facet is `{ field }` (the record property holding the value or
+ * the values) or `{ values(record) }`, plus `label(value)` — the site's own
+ * label helper, so a country reads as its name — and optionally
+ * `include(value)` to keep some values only (a tag of one category),
+ * `sort` (`'label'`, the default; a comparator over `{ value, label }`; or
+ * `'none'` for the order met), and `capitalize` for the legacy upper-cased
+ * first letter of a tag label.
+ */
+export function facetOptions(records, spec) {
+  const out = {}
+  for (const [facet, definition] of Object.entries(spec ?? {})) {
+    const seen = new Map()
+    for (const record of records ?? []) {
+      for (const value of valuesOf(record, definition)) {
+        if (value == null || value === '' || seen.has(value)) continue
+        if (definition.include && !definition.include(value, record)) continue
+        let label = definition.label ? definition.label(value, record) : String(value)
+        if (definition.capitalize) label = capitalize(label)
+        seen.set(value, { value, label: String(label ?? value) })
+      }
+    }
+    const options = [...seen.values()]
+    const sort = definition.sort ?? 'label'
+    if (sort === 'label') options.sort(compareLabels)
+    else if (typeof sort === 'function') options.sort(sort)
+    out[facet] = options
+  }
+  return out
+}
+
+/** `facetOptions` over a reactive record source. */
+export function useFacets(records, spec) {
+  return computed(() => facetOptions(toValue(records), toValue(spec)))
+}

package/src/catalogue/keywordIndex.js

@@ -0,0 +1,289 @@
+import { computed, toValue } from 'vue'
+import { renderPlain } from '../i18n/markdown.js'
+import { useDataPackage } from '../composables/useDataPackage.js'
+import { entityRef } from '../composables/useEntities.js'
+import { sortChronological } from './pagination.js'
+
+// Two search engines, one interface. The standalone sites search nine named
+// fields of the translation record with up to four keyword rows joined by
+// AND/OR — `database.php`'s form. The DXA sites run MySQL's boolean
+// full-text grammar (`+word -word word* "a phrase"` and the relevance
+// operators) over a haystack of the English sheet, which is why their
+// "how to search" page is an essay about operators. They are different
+// products and each site copied its engine unchanged; here each is written
+// once and a site names the one it is.
+//
+// Both read Markdown fields as plain text, through the pipeline every text
+// goes through, so a `*` of emphasis is not searched for and a term written
+// in a heading is found.
+
+const plain = (value) => (value == null ? '' : renderPlain(String(value)).toLowerCase())
+
+function strings(value) {
+  if (value == null) return []
+  if (Array.isArray(value)) return value.flatMap(strings)
+  return [String(value)]
+}
+
+// ── The field grammar ──────────────────────────────────────────────────────
+
+/**
+ * `expand(keyword, lang)` (when given) names alternative spellings of the
+ * same keyword — a glossary term's other spellings, a country's other names
+ * — searched in the same haystack as the keyword itself, so a row matches on
+ * any of them without the site's field map knowing expansion happened.
+ */
+function fieldMatches(getters, field, keyword, item, text, helpers, expand, lang) {
+  const needle = String(keyword ?? '').trim().toLowerCase()
+  if (!needle) return true
+  const getter = getters[field] ?? getters.keyword ?? Object.values(getters)[0]
+  if (!getter) return false
+  const hay = strings(getter(item, text, helpers)).map(plain)
+  if (hay.some((s) => s.includes(needle))) return true
+  if (!expand) return false
+  return (expand(String(keyword ?? '').trim(), lang) ?? []).some((alt) => {
+    const altNeedle = String(alt ?? '').trim().toLowerCase()
+    return altNeedle !== '' && hay.some((s) => s.includes(altNeedle))
+  })
+}
+
+/**
+ * The AND/OR fold of the keyword rows: the first row stands alone, each
+ * following row is joined to the result so far by its own `cond`. Rows with
+ * no keyword are skipped. No row at all matches everything.
+ *
+ * `rank: 'hits'` (Decision D3, legacy's `ORDER BY nn DESC, pkdate ASC`)
+ * reorders the matches by how many of the active rows each one matched, most
+ * first, then chronologically — `sortChronological`'s own rule, undated
+ * last, rather than a second date comparator written here. Left unranked
+ * (the default) a site keeps its own order, page-size and all — this option
+ * exists for a site that wants the legacy order back, not to replace it.
+ */
+function fieldSearch(getters, items, rows, textOf, helpers, { rank, expand, lang } = {}) {
+  const active = (rows ?? []).filter((row) => String(row?.keyword ?? '').trim() !== '')
+  if (active.length === 0) return [...items]
+  const matched = []
+  for (const item of items) {
+    const text = textOf(item)
+    let result = null
+    let hits = 0
+    for (const row of active) {
+      const hit = fieldMatches(getters, row.field, row.keyword, item, text, helpers, expand, lang)
+      if (hit) hits += 1
+      if (result === null) result = hit
+      else if (String(row.cond).toUpperCase() === 'OR') result = result || hit
+      else result = result && hit
+    }
+    if (result === true) matched.push({ item, hits })
+  }
+  if (rank === 'hits') {
+    const chronological = sortChronological(matched.map((m) => m.item))
+    const order = new Map(chronological.map((item, i) => [item, i]))
+    matched.sort((a, b) => order.get(a.item) - order.get(b.item))
+    matched.sort((a, b) => b.hits - a.hits)
+  }
+  return matched.map((m) => m.item)
+}
+
+// ── The boolean grammar ────────────────────────────────────────────────────
+
+/** `+word -word word* "a phrase" ~word >word <word` → terms. */
+export function parseBooleanQuery(input) {
+  const terms = []
+  const re = /([+\-~<>]?)(?:"([^"]+)"|(\S+))/g
+  let match
+  while ((match = re.exec(input ?? '')) !== null) {
+    const [, op, phrase, word] = match
+    let text = (phrase ?? word ?? '').toLowerCase()
+    if (!text) continue
+    let prefix = false
+    if (!phrase && text.endsWith('*')) {
+      prefix = true
+      text = text.slice(0, -1)
+    }
+    if (!text) continue
+    terms.push({ op: op || '', text, prefix, phrase: Boolean(phrase) })
+  }
+  return terms
+}
+
+const REGEXP_SPECIAL = /[.*+?^${}()|[\]\\]/g
+
+function termMatches(hay, term) {
+  if (term.prefix) {
+    return new RegExp(`(?:^|[^\\p{L}\\p{N}_])${term.text.replace(REGEXP_SPECIAL, '\\$&')}`, 'u').test(hay)
+  }
+  return hay.includes(term.text)
+}
+
+/** Rank `items` against a boolean query; `hayOf(item)` is the lower-cased haystack. */
+function booleanSearch(items, input, hayOf, labelOf) {
+  const terms = parseBooleanQuery(input)
+  if (terms.length === 0) return []
+  const required = terms.filter((t) => t.op === '+')
+  const excluded = terms.filter((t) => t.op === '-')
+  const optional = terms.filter((t) => t.op !== '+' && t.op !== '-')
+
+  const scored = []
+  for (const item of items) {
+    const hay = hayOf(item)
+    if (!required.every((t) => termMatches(hay, t))) continue
+    if (excluded.some((t) => termMatches(hay, t))) continue
+    let score = required.length * 2
+    let anyOptional = false
+    for (const t of optional) {
+      if (!termMatches(hay, t)) continue
+      anyOptional = true
+      // `~` counts against, `>` for more, `<` for less — legacy's relevance
+      // operators, as simple weights.
+      score += t.op === '~' ? -1 : t.op === '>' ? 2 : t.op === '<' ? 0.5 : 1
+    }
+    if (!required.length && !anyOptional) continue
+    scored.push({ item, score })
+  }
+  scored.sort((a, b) => b.score - a.score || labelOf(a.item).localeCompare(labelOf(b.item)))
+  return scored.map((s) => s.item)
+}
+
+// ── The composable ─────────────────────────────────────────────────────────
+
+/**
+ * A keyword search over one entity, in one of two grammars.
+ *
+ * `grammar: 'fields'` — `fields` maps a field name to `(record, text) =>
+ * string | string[]`, the strings that field searches (`text` is the
+ * record's translation in `language`); `search(rows)` takes
+ * `[{ field, keyword, cond }]` and folds them with AND/OR. Which fields exist
+ * and what each reads is the site's: the nine of `database.php` are Islamic
+ * Art's, Baroque Art's differ. `rank: 'hits'` and `expand` (below) apply to
+ * this grammar only — the DXA boolean grammar already ranks by score and is
+ * unaffected by either.
+ *
+ * `grammar: 'boolean'` — `haystack(record, text)` returns the strings the
+ * record is searched in; `search(query)` ranks by the boolean grammar.
+ *
+ * `language` (a ref, getter or string) is the translation language the text
+ * is read in — English on every DXA site, the visitor's search language on a
+ * standalone one. The haystacks are computed once per record and language
+ * and dropped when that language's translations load or change, which is
+ * what a site used to do by hand with a `resetSearchIndex()` after
+ * `loadEnglish()`.
+ *
+ * `rank: 'hits'` — off by default, so an existing site's own order (or lack
+ * of one) is untouched. On, `search()` returns matches ordered by how many
+ * of the query's rows they matched, then chronologically — legacy's
+ * `ORDER BY nn DESC, pkdate ASC`. A results page composing this into
+ * `viewer-layout`'s list view passes `sort: false` there so the order this
+ * function already computed is not sorted a second time.
+ *
+ * `expand(keyword, language) => string[]` — alternative spellings of a
+ * keyword, searched alongside it in whichever field the row names. Off by
+ * default. `glossaryExpansion` and `countryExpansion` below are the two
+ * legacy rules (`database_results.php:41,113-136,181-186`); `combineExpansions`
+ * runs both.
+ */
+export function useKeywordIndex(entity, { grammar, fields = {}, haystack, language = 'en', label, rank, expand } = {}) {
+  if (grammar !== 'fields' && grammar !== 'boolean') {
+    throw new Error(`useKeywordIndex: grammar must be "fields" or "boolean", got "${grammar}"`)
+  }
+  const { tr, translations } = useDataPackage()
+  const records = entityRef(entity)
+  const labelOf = label ?? ((record) => plain(record?.name ?? record?.title ?? record?.internal_name ?? record?.id))
+
+  const lang = computed(() => toValue(language) || 'en')
+  const textOf = (record) => tr(entity, record.id, lang.value, 'en')
+
+  // Keyed on the translation map itself: `translations()` hands out one
+  // object per loaded file, so a new object means the file arrived and every
+  // haystack built without it is stale.
+  let cacheFor = null
+  let cache = new Map()
+  function hayOf(record) {
+    const current = translations(entity, lang.value)
+    if (current !== cacheFor) {
+      cacheFor = current
+      cache = new Map()
+    }
+    let hay = cache.get(record.id)
+    if (hay === undefined) {
+      hay = strings(haystack ? haystack(record, textOf(record)) : Object.values(textOf(record)))
+        .map(plain)
+        .join(' \n ')
+      cache.set(record.id, hay)
+    }
+    return hay
+  }
+
+  function search(input) {
+    const items = records.value ?? []
+    if (grammar === 'fields') {
+      return fieldSearch(fields, items, input, textOf, { tr, translations }, { rank, expand, lang: lang.value })
+    }
+    return booleanSearch(items, input, hayOf, labelOf)
+  }
+
+  function reset() {
+    cacheFor = null
+    cache = new Map()
+  }
+
+  return { search, reset, records, language: lang }
+}
+
+// ── Expansion hooks ─────────────────────────────────────────────────────────
+//
+// Both read a term-lookup entity the same way `searchGlossary` does: the
+// translation in `language` falling back to English, never the base record
+// alone, because a spelling or a name is what the visitor typed in and the
+// base record carries neither.
+
+/**
+ * A term equal to one of a glossary entry's spellings, in `language`
+ * (falling back to English), expands to every spelling of that same entry
+ * in that language — legacy's `gl_spellings`/`glossary` lookup
+ * (`database_results.php:104-131`): typing the term used in one spelling
+ * finds the record written with another.
+ */
+export function glossaryExpansion({ entity = 'glossary' } = {}) {
+  return (term, language) => {
+    const needle = String(term ?? '').trim().toLowerCase()
+    if (!needle) return []
+    const { tr } = useDataPackage()
+    for (const record of entityRef(entity).value ?? []) {
+      const t = tr(entity, record.id, language)
+      const spellings = t.spellings?.length ? t.spellings : [record.word]
+      if (spellings.some((s) => String(s ?? '').trim().toLowerCase() === needle)) {
+        return spellings.map((s) => String(s).trim())
+      }
+    }
+    return []
+  }
+}
+
+/**
+ * A term equal to a country's name, in `language` (falling back to
+ * `internal_name`), expands to that country's id — legacy's
+ * `getKeywordCountry` (`database_results.php:27-51,223-224,291-293`): typing
+ * "Egypt" also finds the records held in Egypt. Applies to whichever field a
+ * row names; the field's own getter decides whether a record's country is
+ * part of what it searches — the `keyword` and `location` fields on the
+ * standalone form did, in legacy.
+ */
+export function countryExpansion({ entity = 'countries' } = {}) {
+  return (term, language) => {
+    const needle = String(term ?? '').trim().toLowerCase()
+    if (!needle) return []
+    const { tr } = useDataPackage()
+    const out = []
+    for (const record of entityRef(entity).value ?? []) {
+      const name = tr(entity, record.id, language).name ?? record.internal_name ?? record.id
+      if (String(name).trim().toLowerCase() === needle) out.push(record.id)
+    }
+    return out
+  }
+}
+
+/** Runs every expansion given and concatenates what each returns. */
+export function combineExpansions(...expansions) {
+  return (term, language) => expansions.flatMap((expand) => expand(term, language) ?? [])
+}