@museumwnf/viewer-core 1.14.0

package/src/record/collectionTree.js

@@ -0,0 +1,307 @@
+import { computed } from 'vue'
+import { entityRef } from '../composables/useEntities.js'
+
+// Three sites each walked `collections.json` from a purpose marker by
+// `parent_id` and `display_order`, and each wrote the same reverse
+// "collections containing this item" scan by hand (islamicart, baroqueart,
+// sharinghistory). A fourth family — the DXA sites — carries the identical
+// shape pre-built as `themes.json` (`sub_themes[]`, `pictures[]`), because
+// its importer nests the tree rather than flattening it with `parent_id`.
+// This is that walk, written once: a pure indexer over either shape, and a
+// composable over `entityRef` for the reactive form a page reads.
+//
+// A node's own items are read from whichever shape the record carries:
+// `items: [{ id, ... }]` (collections) or a flat `item_ids` — a theme node
+// has neither; its content is `pictures[].picture_item_id`, so the themes
+// adapter passes its own extractor rather than reusing this one.
+function itemIdsOfCollection(node) {
+  if (Array.isArray(node?.items)) {
+    return node.items.map((item) => (item && typeof item === 'object' ? item.id : item)).filter((id) => id != null)
+  }
+  if (Array.isArray(node?.item_ids)) {
+    return node.item_ids.filter((id) => id != null)
+  }
+  return []
+}
+
+function itemIdsOfTheme(node) {
+  return Array.isArray(node?.pictures)
+    ? node.pictures.map((picture) => picture?.picture_item_id).filter((id) => id != null)
+    : []
+}
+
+// Legacy's "unordered records sort last" convention (the three composables
+// this replaces all wrote `?? 9999` by hand); carried over rather than
+// improved, since a package with more than 9999 siblings under one node
+// does not exist.
+const NO_ORDER = 9999
+
+function orderOf(node, order) {
+  const value = node?.[order]
+  return typeof value === 'number' ? value : NO_ORDER
+}
+
+/**
+ * The shared indexer behind `buildCollectionTree` and
+ * `collectionTreeFromThemes`: a flat array of `{ id, parent_id, ... }`
+ * nodes, a `rootId` among them (or a sentinel none of them carries, for a
+ * tree with no root record of its own — see `collectionTreeFromThemes`),
+ * and the interface both entry points hand back. Carries `entity` and `source`
+ * so a consumer handed a built tree can read the nodes' texts without being
+ * told the entity a second time.
+ */
+function buildIndex(nodes, rootId, { childType, order = 'display_order', itemIdsOf = itemIdsOfCollection, entity, source } = {}) {
+  const byIdMap = new Map(nodes.map((node) => [node.id, node]))
+  const childIds = new Map() // parent id → ordered child ids
+  for (const node of nodes) {
+    if (node.parent_id == null) continue
+    if (!childIds.has(node.parent_id)) childIds.set(node.parent_id, [])
+    childIds.get(node.parent_id).push(node.id)
+  }
+  for (const list of childIds.values()) {
+    list.sort((a, b) => orderOf(byIdMap.get(a), order) - orderOf(byIdMap.get(b), order))
+  }
+
+  // A node's depth below the root: the root itself is 0, its direct
+  // children 1, and so on — bounded by `rootId`, not by how far the
+  // `parent_id` chain actually goes (an explicit `rootId` partway down the
+  // data is depth 0 for this tree, even though it has ancestors of its own).
+  // `parents()` below walks the same chain but doesn't stop at `rootId`,
+  // because a breadcrumb wants the true ancestry; this does, because a
+  // depth-indexed `childType` cares only about position within this tree.
+  function depthOf(id) {
+    let depth = 0
+    let current = byIdMap.get(id)
+    const seen = new Set()
+    while (current && current.id !== rootId && current.parent_id != null && !seen.has(current.id)) {
+      seen.add(current.id)
+      depth++
+      if (current.parent_id === rootId) break
+      current = byIdMap.get(current.parent_id)
+    }
+    return depth
+  }
+
+  // `childType` filters a node's children, in one of three forms:
+  //  - a string: applied at every depth, not just the root's — a marker's
+  //    direct children are sometimes a mix of the real tree and siblings
+  //    that only look like it (sharinghistory's country-specific "National
+  //    Context" collections sit next to the real themes), and a caller who
+  //    names the type wants it held to at every level, not only the first.
+  //  - an array, indexed by depth below the root: `childType[0]` filters the
+  //    root's children, `childType[1]` filters their children, and so on.
+  //    A depth past the end of the array is unfiltered. For example,
+  //    sharinghistory's exhibitions → themes → chapters uses `['exhibition',
+  //    'theme', 'subtheme']` because the root's direct children are
+  //    exhibitions (depth 0), their children are themes (depth 1), and so on;
+  //    a tree rooted at one exhibition uses `['theme', 'subtheme']` instead.
+  //    A single type at every depth (e.g. `['theme', 'theme', …]`) is not the
+  //    pattern to use when levels differ; it drops real nodes.
+  //  - a function `(node, depth, parent) => boolean`, for a rule neither of
+  //    the above expresses.
+  function children(id) {
+    const kids = (childIds.get(id) ?? []).map((cid) => byIdMap.get(cid)).filter(Boolean)
+    if (!childType) return kids
+    if (typeof childType === 'function') {
+      const parent = byIdMap.get(id) ?? null
+      const depth = depthOf(id) + 1
+      return kids.filter((node) => childType(node, depth, parent))
+    }
+    if (Array.isArray(childType)) {
+      const type = childType[depthOf(id)]
+      return type ? kids.filter((node) => node.type === type) : kids
+    }
+    return kids.filter((node) => node.type === childType)
+  }
+
+  function parents(id) {
+    const chain = []
+    let current = byIdMap.get(id)
+    while (current && current.parent_id != null && current.parent_id !== current.id) {
+      const parent = byIdMap.get(current.parent_id)
+      if (!parent) break
+      chain.unshift(parent)
+      current = parent
+    }
+    return chain
+  }
+
+  function breadcrumb(id) {
+    const node = byIdMap.get(id)
+    return node ? [...parents(id), node] : []
+  }
+
+  /** A node's own item ids plus every descendant's, depth-first, each once. */
+  function itemsUnder(id) {
+    const node = byIdMap.get(id)
+    if (!node) return []
+    const seen = new Set()
+    const out = []
+    const visit = (current) => {
+      for (const itemId of itemIdsOf(current)) {
+        if (!seen.has(itemId)) {
+          seen.add(itemId)
+          out.push(itemId)
+        }
+      }
+      for (const child of children(current.id)) visit(child)
+    }
+    visit(node)
+    return out
+  }
+
+  // The reverse lookup every site wrote by hand: which collections carry
+  // this item directly. Not recursive — a page's items do not make its
+  // theme "contain" them for this purpose, the way `itemsUnder` treats them;
+  // a caller wanting the enclosing theme or exhibition walks up with
+  // `parents` from what this returns, as the sites' own link-builders did.
+  function containing(itemId) {
+    const out = []
+    for (const node of byIdMap.values()) {
+      if (itemIdsOf(node).includes(itemId)) out.push(node)
+    }
+    return out
+  }
+
+  // The tree, flattened depth-first, root excluded (the root is the anchor
+  // the tree hangs from, not a page a visitor lands on). `previous`/`next`
+  // read this sequence by index, which is what makes them cross a branch
+  // boundary for free: the last node of one branch is simply followed in
+  // the array by the first node of the next, container or leaf alike.
+  function walk() {
+    const out = []
+    const visit = (id) => {
+      for (const child of children(id)) {
+        out.push(child)
+        visit(child.id)
+      }
+    }
+    if (rootId != null) visit(rootId)
+    return out
+  }
+
+  function previous(id) {
+    const sequence = walk()
+    const index = sequence.findIndex((node) => node.id === id)
+    return index > 0 ? sequence[index - 1] : null
+  }
+
+  function next(id) {
+    const sequence = walk()
+    const index = sequence.findIndex((node) => node.id === id)
+    return index !== -1 && index < sequence.length - 1 ? sequence[index + 1] : null
+  }
+
+  return {
+    root: rootId != null ? (byIdMap.get(rootId) ?? null) : null,
+    byId: byIdMap,
+    children,
+    parents,
+    breadcrumb,
+    itemsUnder,
+    containing,
+    walk,
+    previous,
+    next,
+    entity,
+    source,
+  }
+}
+
+/**
+ * A collection tree rooted at a purpose marker, over a flat
+ * `collections.json`-shaped array: `{ id, parent_id, display_order, type,
+ * purpose, items }`. `purpose` finds the root by its `purpose` field (the
+ * anchor the importer keys the tree from, e.g. `"exhibitions-root"`);
+ * `rootId` takes an id directly, for the sites that resolve a marker's
+ * single child as the real root themselves (islamicart's Artistic
+ * Introduction). Exactly one of the two is expected. `childType` filters a
+ * node's children by `type`: a string applies the same type at every depth
+ * (sharinghistory's themes, sitting next to National Context collections
+ * that are not themes); an array is indexed by depth below the root, where
+ * `childType[0]` filters the root's children, `childType[1]` filters their
+ * children, and so on (sharinghistory's exhibitions → themes → chapters uses
+ * `['exhibition', 'theme', 'subtheme']`, and a tree rooted at one exhibition
+ * uses `['theme', 'subtheme']`); a depth past the end is unfiltered; a
+ * function `(node, depth, parent) => boolean` covers anything else. Pure —
+ * no reactivity, so it is also what a Node script or a one-off script can
+ * call directly. `entity` is the translations entity the tree reads (default
+ * `'collections'`); `source` is always `'collections'`.
+ */
+export function buildCollectionTree(collections, { purpose, rootId, childType, order = 'display_order', entity = 'collections' } = {}) {
+  const nodes = collections ?? []
+  const resolvedRootId = rootId ?? nodes.find((node) => node.purpose === purpose)?.id ?? null
+  return buildIndex(nodes, resolvedRootId, { childType, order, itemIdsOf: itemIdsOfCollection, entity, source: 'collections' })
+}
+
+// A sentinel no real record's id collides with: `themes.json` is already the
+// whole tree, an ordered array of top-level themes with `sub_themes[]`
+// nested inside each — there is no marker record to key a root on. Flatten
+// it to the same `{ id, parent_id }` shape `buildIndex` reads, with every
+// top-level theme's synthetic parent set to this sentinel, and `root` comes
+// back null: there genuinely isn't one, and no site has read it from
+// `themes.json` before this.
+const THEMES_ROOT = Symbol('collectionTree.themesRoot')
+
+function flattenThemes(themes, parentId) {
+  const out = []
+  for (const theme of themes ?? []) {
+    const { sub_themes: subThemes, ...rest } = theme
+    out.push({ ...rest, parent_id: parentId })
+    out.push(...flattenThemes(subThemes, theme.id))
+  }
+  return out
+}
+
+/**
+ * The same interface as `buildCollectionTree`, from a `themes.json` shape
+ * (top-level themes, each with `sub_themes[]` and `pictures[]`) instead of a
+ * flat, `parent_id`-linked `collections.json`. `root` is always null — see
+ * above; `walk`/`children`/… all work the same from the (nulled) top. `entity`
+ * is the translations entity the tree reads (default `'themes'`); `source` is
+ * always `'themes'`.
+ */
+export function collectionTreeFromThemes(themes, { childType, order = 'display_order', entity = 'themes' } = {}) {
+  const nodes = flattenThemes(themes, THEMES_ROOT)
+  return buildIndex(nodes, THEMES_ROOT, { childType, order, itemIdsOf: itemIdsOfTheme, entity, source: 'themes' })
+}
+
+/**
+ * The reactive form: `useCollectionTree({ purpose | rootId, childType?,
+ * entity = 'collections', order = 'display_order' })` (see
+ * `buildCollectionTree` for the forms `childType` accepts) for the
+ * `collections.json` shape, or `useCollectionTree({ source: 'themes',
+ * entity: 'themes' })` for a `themes.json` package, where `purpose`/`rootId`
+ * do not apply (see `collectionTreeFromThemes`). Reads `entity` through
+ * `entityRef`, so the tree is empty (not an error) before that entity's
+ * chunk has arrived, and recomputes once it does — a website loads the
+ * entity itself, through `meta.entities` or `loadEntities`, exactly as it
+ * does for every other record. Returns `entity` (the translations entity the
+ * tree reads, the value resolved from the options) and `source` (`'collections'`
+ * or `'themes'`), so a consumer handed a built tree can read the nodes' texts
+ * without being told the entity a second time.
+ */
+export function useCollectionTree(options = {}) {
+  const { entity = 'collections', source = 'collections' } = options
+  const records = entityRef(entity)
+  const tree = computed(() => {
+    const nodes = records.value ?? []
+    return source === 'themes' ? collectionTreeFromThemes(nodes, options) : buildCollectionTree(nodes, options)
+  })
+  return {
+    root: computed(() => tree.value.root),
+    byId: computed(() => tree.value.byId),
+    children: (id) => tree.value.children(id),
+    parents: (id) => tree.value.parents(id),
+    breadcrumb: (id) => tree.value.breadcrumb(id),
+    itemsUnder: (id) => tree.value.itemsUnder(id),
+    containing: (itemId) => tree.value.containing(itemId),
+    walk: () => tree.value.walk(),
+    previous: (id) => tree.value.previous(id),
+    next: (id) => tree.value.next(id),
+    // entity and source are fixed by the options at call time and never change;
+    // a consumer reads them as plain strings, not refs (entityRef and pkg.tr lookups).
+    entity,
+    source,
+  }
+}

package/src/record/derivations.js

@@ -0,0 +1,154 @@
+import { computed, ref, toValue } from 'vue'
+import { useDataPackage } from '../composables/useDataPackage.js'
+import { byId, entityRef } from '../composables/useEntities.js'
+import { renderPlain } from '../i18n/markdown.js'
+import { roundOutward } from '../catalogue/dates.js'
+
+const BASE_LANGUAGE = 'en'
+
+// Four derivations every record page makes, written seven times.
+
+// ── The glossary popup ─────────────────────────────────────────────────────
+//
+// The renderer marks every glossary spelling as
+// `<span class="gloss-term" data-gid="…">` while it parses. Those spans are
+// inside `v-html`, so nothing binds to them one by one: one listener on the
+// container reads the click and answers with the term.
+
+/**
+ * `{ active, onClick, close }`: attach `onClick` to the element the sheet
+ * renders into; `active` is `{ id, word, spelling, definition }` for the
+ * term clicked, null otherwise. `entries` is the `glossary` list of
+ * `useRecordSheet` (a ref, getter or array).
+ */
+export function useGlossaryPopup(entries) {
+  const active = ref(null)
+  function onClick(event) {
+    const element = event?.target?.closest?.('.gloss-term')
+    if (!element) return
+    event.preventDefault()
+    const id = element.dataset.gid
+    const entry = (toValue(entries) ?? []).find((e) => e.id === id)
+    active.value = {
+      id,
+      spelling: element.textContent,
+      word: entry?.word ?? element.textContent,
+      definition: entry?.definition ?? '',
+    }
+  }
+  function close() {
+    active.value = null
+  }
+  return { active, onClick, close }
+}
+
+/**
+ * The glossary terms whose spelling starts with `input`, in `language`
+ * (falling back to English), for a glossary search box: `[{ id, word,
+ * spelling, definition }]`, one per term, sorted by spelling.
+ */
+export function searchGlossary(input, language, { entity = 'glossary' } = {}) {
+  const needle = String(input ?? '').trim().toLowerCase()
+  if (!needle) return []
+  const { translations } = useDataPackage()
+  const rows = translations(entity, language)
+  const fallback = translations(entity, BASE_LANGUAGE)
+  const out = []
+  for (const term of entityRef(entity).value ?? []) {
+    const t = rows[term.id] ?? fallback[term.id] ?? {}
+    const spellings = t.spellings?.length ? t.spellings : [term.word]
+    for (const spelling of spellings) {
+      if (String(spelling ?? '').toLowerCase().startsWith(needle)) {
+        out.push({ id: term.id, word: term.word, spelling: String(spelling).trim(), definition: t.definition ?? '' })
+        break
+      }
+    }
+  }
+  return out.sort((a, b) => a.spelling.localeCompare(b.spelling))
+}
+
+// ── Citation ───────────────────────────────────────────────────────────────
+
+/**
+ * The sentence both families print under a sheet:
+ * `Author "Name" in Project, Publisher, Year. Permalink` — assembled here in
+ * that order, from parts, rather than written into a text with holes in it.
+ * `inWord` is the site's `t('record.citation.in')`. Parts that are missing
+ * are left out with their punctuation.
+ */
+export function citation({ author, name, project, publisher = 'Museum With No Frontiers', year, permalink, inWord = 'in' } = {}) {
+  const title = renderPlain(name ?? '')
+  if (!title) return ''
+  const when = year ?? new Date().getFullYear()
+  const where = [project, publisher].filter(Boolean).join(', ')
+  const parts = []
+  if (author) parts.push(String(author).trim())
+  parts.push(`"${title}"`)
+  if (where) parts.push(`${inWord} ${where},`)
+  let sentence = `${parts.join(' ')} ${when}.`
+  if (permalink) sentence += ` ${permalink}`
+  return sentence
+}
+
+// ── Related records ────────────────────────────────────────────────────────
+
+/**
+ * A record's `related_items`, split by whether the package carries them:
+ * `inPackage` is `[{ reference, record, justification }]` with the
+ * justification in `language` (falling back to English); `outside` is the
+ * references the package does not hold, kept as the references they are — a
+ * link is never dropped for being unresolvable, and never invented either.
+ */
+export function relatedRecords(record, { entity = 'items', language = BASE_LANGUAGE, field = 'related_items' } = {}) {
+  const index = byId(entity).value
+  const inPackage = []
+  const outside = []
+  const seen = new Set()
+  for (const reference of record?.[field] ?? []) {
+    if (!reference || seen.has(reference.id)) continue
+    seen.add(reference.id)
+    const found = reference.in_package === false ? null : index.get(reference.id)
+    if (!found) {
+      outside.push(reference)
+      continue
+    }
+    const justifications = reference.justifications ?? {}
+    inPackage.push({
+      reference,
+      record: found,
+      justification: justifications[language] ?? justifications[BASE_LANGUAGE] ?? '',
+    })
+  }
+  return { inPackage, outside }
+}
+
+/** `relatedRecords` over reactive sources. */
+export function useRelatedRecords(record, options = {}) {
+  return computed(() => relatedRecords(toValue(record), { ...options, language: toValue(options.language) ?? BASE_LANGUAGE }))
+}
+
+// ── The timeline link ──────────────────────────────────────────────────────
+
+/**
+ * The route location of the timeline results for a record's country and
+ * dates, or null when the record has neither a country nor a date. `name`
+ * is the site's timeline-results route; `keys` the query keys it reads
+ * (`country`, `begin`, `end` by default); `country(record)` the value the
+ * route wants for the country (the id by default — a site whose timeline
+ * reads legacy codes passes its own); `round` rounds the dates outward to
+ * the century, as the DXA "Timeline for this item" does.
+ */
+export function timelineLinkFor(record, { name = 'timeline-results', keys = {}, country, round = false } = {}) {
+  if (!record) return null
+  const countryValue = country ? country(record) : record.country_id
+  const start = typeof record.start_date === 'number' ? record.start_date : null
+  const end = typeof record.end_date === 'number' ? record.end_date : null
+  if (!countryValue && start == null && end == null) return null
+  let [from, to] = [start, end]
+  if (round) [from, to] = roundOutward(start ?? undefined, end ?? undefined)
+  const query = {}
+  if (countryValue) query[keys.country ?? 'country'] = String(countryValue)
+  if (from != null) query[keys.begin ?? 'begin'] = String(from)
+  if (to != null) query[keys.end ?? 'end'] = String(to)
+  return { name, query }
+}

package/src/record/partners.js

@@ -0,0 +1,87 @@
+// Seven partner lists group by country seven ways. The standalone sites
+// (islamicart, baroqueart, sharinghistory) bucket each country's partners
+// into "main" and "associated" on a `level` field and render an accordion;
+// the DXA sites (carpets and its siblings) group the same way but add an
+// A-Z / Z-A toggle and no tiers at all. Both are this one derivation with a
+// couple of options — pure, so the site's own view supplies the toggle and
+// the label lookup.
+//
+// `parent_id` is carried on a third of the standalone partners and read
+// nowhere: legacy nested an associated partner under the main partner it
+// belongs to, and the port flattened that into the country column instead.
+// `partnerHierarchy` is that relationship, read once.
+
+/**
+ * Whether `record` counts as a main (rather than associated) partner.
+ * `tier` names the field the converged partner shape carries (`level`).
+ * A record is associated only when its tier value is a non-empty value
+ * other than `'partner'` (legacy values: `'associated_partner'`,
+ * `'minor_contributor'`); `null`, `undefined`, `''`, or `'partner'` mean
+ * main. This is necessary because exporters emit `level: null` for every
+ * partner without curated hierarchy. Without a `tier` at all there is nothing
+ * to divide records on, so every record is main, which is what a caller with
+ * no tiers (the DXA lists) wants.
+ */
+function isMainTier(record, tier) {
+  if (!tier) return true
+  const tierValue = record?.[tier]
+  // Treat null, undefined, empty string, or 'partner' as main
+  return tierValue == null || tierValue === '' || tierValue === 'partner'
+}
+
+/**
+ * Partner records grouped by country: `[{ country, label, main, associated
+ * }]`, one entry per distinct `country_id` (partners with none share a
+ * `null` group), sorted by `label`, ascending unless `order: 'desc'`.
+ * `label(country)` names a group's country — the caller's own lookup, the
+ * same shape as a facet's `label(value)` — since a partner record carries
+ * only the id. `tier` names the field that marks a main partner (see
+ * `isMainTier`); without it every record lands in `main` and `associated`
+ * is always empty, which covers the DXA lists' plain grouping. Partners
+ * keep the relative order `records` was given in within each tier — sorting
+ * them by their own label is the view's concern, not this derivation's.
+ */
+export function groupByCountry(records, { label, tier, order = 'asc' } = {}) {
+  const groups = new Map()
+  for (const record of records ?? []) {
+    const country = record?.country_id ?? null
+    if (!groups.has(country)) groups.set(country, { country, main: [], associated: [] })
+    const group = groups.get(country)
+    ;(isMainTier(record, tier) ? group.main : group.associated).push(record)
+  }
+  const rows = [...groups.values()].map((group) => ({ ...group, label: label ? label(group.country) : group.country }))
+  rows.sort((a, b) => String(a.label).localeCompare(String(b.label)))
+  return order === 'desc' ? rows.reverse() : rows
+}
+
+/**
+ * The partner hierarchy `parent_id` encodes: `children(id)` (a partner's
+ * associated partners), `parentOf(id)` (the main partner it belongs to, or
+ * null), `roots` (every partner with no parent in the list, or whose
+ * `parent_id` points outside it). A partner referencing a `parent_id` this
+ * list does not carry is treated as a root rather than dropped — the same
+ * "keep the reference, don't invent or discard" rule `relatedRecords` uses.
+ */
+export function partnerHierarchy(partners) {
+  const list = partners ?? []
+  const byId = new Map(list.map((partner) => [partner.id, partner]))
+  const childrenOf = new Map()
+  const roots = []
+  for (const partner of list) {
+    const parent = partner?.parent_id != null ? byId.get(partner.parent_id) : null
+    if (parent) {
+      if (!childrenOf.has(parent.id)) childrenOf.set(parent.id, [])
+      childrenOf.get(parent.id).push(partner)
+    } else {
+      roots.push(partner)
+    }
+  }
+  return {
+    children: (id) => childrenOf.get(id) ?? [],
+    parentOf: (id) => {
+      const partner = byId.get(id)
+      return partner?.parent_id != null ? (byId.get(partner.parent_id) ?? null) : null
+    },
+    roots,
+  }
+}