@museumwnf/viewer-core 2.1.0 → 2.2.0

package/README.md

@@ -470,14 +470,14 @@ under the main partner it belongs to.
 | --- | --- |
 | `groupByCountry(records, { label, tier?, order = 'asc' })` | `[{ country, label, main, associated }]`, one entry per distinct `country_id`, sorted by `label`. `label(country)` names a group's country, the same shape as a facet's `label(value)`. `tier` names the field that marks a main partner (the converged shape's `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. Without a `tier` every record is main, which is the DXA lists' plain grouping. Partners keep the order `records` was given in within each tier. |
 | `partnerHierarchy(partners)` | `{ children(id), parentOf(id), roots }` from `parent_id`: `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. |
-| `partnerView(partner, text, ctx)` | The view-model every rendering of one partner reads — `@museumwnf/viewer-layout`'s `PartnerPanel` in each of its variants: `{ id, type, name (inline HTML), plainName, city, country, location, logos: [{ url, alt, type }], pictures: [{ url, alt, caption, photographer, copyright }], description (block HTML), contact: { address (block HTML), phone, fax, email, website: { url, label } \| null, links: [{ url, label }] }, persons: [{ title, name, phone, fax, email }], hasContact, map: { latitude, longitude, zoom, label } \| null, itemCount, hidden, route, objectsRoute }`. `text` is the partner's translation in the language shown. `ctx` carries only what differs by family: `countryLabel(id)`, the renderers (`md`, `mdInline`, `mdStrip`, the package's by default), `route(partner)`, `objectsRoute(partner)` and `hidden(partner)` (a hidden partner keeps its name and loses both links). Contact persons come from `contact_persons`, in order, keeping those with a name or a title. A picture's caption is its `alt_text`. A website or link with no scheme gets `https://`; any scheme other than `http(s)` is dropped. |
+| `partnerView(partner, text, ctx)` | The view-model every rendering of one partner reads — `@museumwnf/viewer-layout`'s `PartnerPanel` in each of its variants: `{ id, type, name (inline HTML), plainName, city, country, location, logos: [{ url, alt, type }], pictures: [{ url, alt, caption, photographer, copyright }], description (block HTML), contact: { address (block HTML), phone, fax, email, website: { url, label } \| null, links: [{ url, label }] }, persons: [{ title, name, phone, fax, email }], hasContact, map: { latitude, longitude, zoom, label } \| null, itemCount, hidden, route, objectsRoute }`. `text` is the partner's translation in the language shown. `ctx` carries only what differs by family: `countryLabel(id)`, the renderers (`md`, `mdInline`, `mdStrip`, the package's by default), `route(partner)`, `objectsRoute(partner)` and `hidden(partner)` (a hidden partner keeps its name and loses both links). Contact persons come from `contact_persons`, in order, keeping those with a name or a title (the legacy `contact_person_1`/`_2` pair is not read). A picture's caption is its `alt_text`. A website or link with no scheme gets `https://`; any scheme other than `http(s)` is dropped. |
 
 ### Conventions
 
 | Export | Meaning |
 | --- | --- |
 | `useSection()` | the `meta.section` of the current route — see Routing |
-| `useFeaturedRecord(entity, { withImage = true, seed })` | one record at random for a landing page's spotlight, among those with an image; null until the entity is loaded; `seed` pins the pick |
+| `useFeaturedRecord(entity, { withImage = true, seed, filter })` | one record at random for a landing page's spotlight, among those with an image; null until the entity is loaded; `seed` pins the pick; `filter(record)` applies a site's own visible rule first |
 | `sectionMeta(chrome = [])` | returns `meta(section, ...entities) => ({ section, entities: [...chrome, ...entities] })` — a route's `meta` in one call, `chrome` being the entities every page of the site loads regardless of which one it is |
 | `mwnfLinks` | the portal and sibling-site addresses the four DXA configs each repeat under `links` — frozen, spread into a site's own `links` rather than retyped |
 
@@ -638,6 +638,49 @@ export const { tr, md, mdInline, mdStrip, labelOf, loadEnglish } = catalogue
 | `index(name, key = 'id')` | a `Map` of `entity(name)`'s records by `key` — the visible ones, unlike `byId` |
 | `availableLanguages`, `loadTranslations`, `translations` | the package's own, re-exported so a site reads everything through the one object |
 
+### The catalogue data layer
+
+`useCatalogue` is `useCatalogueData` plus what a catalogue site — a
+standalone product, or a new product scaffolded from `website-template` —
+otherwise re-types for itself: the catalogue entities, their lookups, the
+labels, the routes and the one result row. A site calls it once, in its
+`data.js`, and keeps next to it only what is its own (a scope rule, a
+collection tree, its legacy address mappings).
+
+```js
+import { useCatalogue } from '@museumwnf/viewer-core'
+
+export const data = useCatalogue({
+  eager: ['items', 'countries', 'partners', 'dynasties', 'glossary'],
+  visible: { items: (item) => item.display_status !== 'N' },
+})
+data.loadEnglish()
+
+export const { items, itemRow, countryLabel, tr, md, mdInline } = data
+```
+
+| Export | Meaning |
+| --- | --- |
+| `useCatalogue(options)` | `useCatalogueData(options)`'s own return, plus: `items`, `countries`, `partners`, `dynasties` (the visible records, `null` until loaded); `itemById` (every item, the visible rule not applied — for a page that deliberately shows a hidden one), `partnerById`, `countryById`, `dynastyById`; `itemLabel(item)`, `countryLabel(id)`, `partnerLabel(id)`, `dynastyLabel(id)` (plain text, `''` for nothing); `itemRoute(item)`, `partnerRoute(partner)` (the `item`/`partner` routes by name); `itemRow(item, meta = ['country', 'dates'])` — the row `RecordList`/`RecordGrid`/`RelatedRecords` share, `meta` naming what follows the name in order: `'country'`, `'dates'`, `'location'`, `'dynasties'`, `'holder'` (the partner, only when the package carries it), or a function `(item, text) => string` |
+| `CATALOGUE_PAGE_SIZE`, `CATALOGUE_DATE_MODE` | `20` and `'overlap'`: the standalone pages' size and date rule (decision D5) — named apart from `/dxa`'s `PAGE_SIZE`/`DATE_MODE` (`9`, `'contain'`), which a DXA site imports next to this root |
+| `objectsAndMonumentsSummary({ matching, t })` | legacy's "[N objects, M monuments]", a results spec's `summary` |
+
+The field search of the legacy `database.php` form — keyword rows each
+naming a field, folded with AND/OR — around `useKeywordIndex`'s `fields`
+grammar:
+
+| Export | Meaning |
+| --- | --- |
+| `searchFields({ dynastyLabel })` | the haystack of each field, as legacy's form searched it: `keyword`, `name`, `location`, `provenance`, `patron`, `artist`, `material`, `other`, and `dynasty` when a `dynastyLabel` is given |
+| `searchFieldOptions(fields)` | `[{ key, label }]` (entry names), in legacy's order, for the fields `fields` carries — `SearchFormView`'s `fields` |
+| `useSearchFieldOptions(fields)`, `searchFieldLabel(key, t)` | the same resolved, `[{ value, label }]`, for a select a site draws itself; one field's label |
+| `searchRows(filters, count = 4)`, `searchRowKeys(count = 4)` | the keyword rows the query carries (`q`/`field`, then `qN`/`fieldN`/`opN`), and their query keys for a results spec's `keys` |
+| `searchedFor(filters, t, { rows, extras })`, `searchSummary(ctx, options)` | the "Name: "bowl" · OR Location: "Cairo" · From 900 · Language: FR" line — `extras`, `(filters, t) => string`, append a site's own parts — and the results summary built on it (what was searched, or all items; then the count) |
+| `useFieldSearch({ fields, entity = 'items', rows = 4, rank = 'hits', expand })` | one long-lived index (the glossary and country expansions by default), its search language following the query's `lang`; `narrow(list, filters)` is a results spec's `narrow` — the matches in rank order, kept to the scoped `list`. Pass `sort: false` to the spec. |
+
+`useFeaturedRecord(entity, { filter })` narrows the candidates by a site's
+own visible rule first: it reads the raw entity.
+
 ### Routing
 
 The convention, applied by the router every website shares:

package/package.json

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

@@ -0,0 +1,128 @@
+import { useCatalogueData } from '../composables/useCatalogueData.js'
+import { byId } from '../composables/useEntities.js'
+
+// The catalogue data layer: what a website built on the generic entries —
+// the standalone products, and every new product scaffolded from
+// `website-template` — re-typed around `useCatalogueData` for itself, three
+// times (inventory-app#2037): the entity refs and lookups a catalogue reads,
+// the label and route helpers, the one result row every list shows, the
+// "[N objects, M monuments]" count. A site keeps one instance of it, in its
+// `data.js`, next to what is genuinely its own (a scope rule, a collection
+// tree, its legacy address mappings).
+//
+// The DXA families have their own layer (`@museumwnf/viewer-core/dxa`), over
+// the same `useCatalogueData`; nothing here reads it.
+
+/** Twenty rows a page: the legacy standalone pages' own size. */
+export const CATALOGUE_PAGE_SIZE = 20
+
+/**
+ * The standalone date rule (decision D5): a record overlapping the window
+ * counts, a record with one date is tolerated. The DXA families contain
+ * (`@museumwnf/viewer-core/dxa`'s `DATE_MODE`); a site names its rule once.
+ */
+export const CATALOGUE_DATE_MODE = 'overlap'
+
+/**
+ * The website's catalogue: everything `useCatalogueData` returns, plus the
+ * catalogue entities, their lookups, the labels, the routes and the result
+ * row. Takes `useCatalogueData`'s own options (`eager`, `defaultLanguage`,
+ * `visible`, `glossary`); called once, at the top of the site's `data.js`.
+ *
+ * - `items`, `countries`, `partners`, `dynasties`: the visible records
+ *   (`visible` applies), `null` until loaded.
+ * - `itemById`: every item, the visible rule not applied — a page that
+ *   deliberately shows a hidden item (a timeline's illustration) reads it.
+ *   `partnerById`, `countryById`, `dynastyById`: the visible records.
+ * - `itemLabel(item)`, `countryLabel(id)`, `partnerLabel(id)`,
+ *   `dynastyLabel(id)`: plain text, `''` for nothing.
+ * - `itemRoute(item)`, `partnerRoute(partner)`: the `item` and `partner`
+ *   routes by name.
+ * - `itemRow(item, meta)`: the row `RecordList`/`RecordGrid`/
+ *   `RelatedRecords` share. `meta` lists what follows the name, in order:
+ *   `'country'`, `'dates'`, `'location'`, `'dynasties'`, `'holder'` (the
+ *   partner's name, only when the package carries the partner, so a label
+ *   is never an id), or a function `(item, text) => string`.
+ */
+export function useCatalogue(options = {}) {
+  const data = useCatalogueData(options)
+  const { tr, labelOf, mdInline } = data
+
+  const items = data.entity('items')
+  const countries = data.entity('countries')
+  const partners = data.entity('partners')
+  const dynasties = data.entity('dynasties')
+
+  const itemById = byId('items')
+  const partnerById = data.index('partners')
+  const countryById = data.index('countries')
+  const dynastyById = data.index('dynasties')
+
+  const itemLabel = (item) => (item ? labelOf('items', item.id) : '')
+  const countryLabel = (id) => (id ? labelOf('countries', id) : '')
+  const partnerLabel = (id) => (id ? labelOf('partners', id) : '')
+  const dynastyLabel = (id) => (id ? labelOf('dynasties', id) : '')
+
+  const itemRoute = (item) => ({ name: 'item', params: { id: item.id } })
+  const partnerRoute = (partner) => ({ name: 'partner', params: { id: partner.id } })
+
+  const META = {
+    country: (item) => countryLabel(item.country_id),
+    dates: (item, text) => text.dates,
+    location: (item, text) => text.location,
+    dynasties: (item) => (item.dynasty_ids ?? []).map(dynastyLabel).filter(Boolean).join(', '),
+    holder: (item) => (partnerById.value.has(item.partner_id) ? partnerLabel(item.partner_id) : ''),
+  }
+
+  function itemRow(item, meta = ['country', 'dates']) {
+    const text = tr('items', item.id)
+    return {
+      id: item.id,
+      image: item.images?.[0]?.url ?? '',
+      imageAlt: itemLabel(item),
+      name: mdInline(text.name ?? item.internal_name ?? item.id),
+      meta: meta
+        .map((part) => (typeof part === 'function' ? part(item, text) : META[part]?.(item, text)))
+        .filter(Boolean),
+      badge: item.type ?? '',
+      to: itemRoute(item),
+    }
+  }
+
+  return {
+    ...data,
+    items,
+    countries,
+    partners,
+    dynasties,
+    itemById,
+    partnerById,
+    countryById,
+    dynastyById,
+    itemLabel,
+    countryLabel,
+    partnerLabel,
+    dynastyLabel,
+    itemRoute,
+    partnerRoute,
+    itemRow,
+  }
+}
+
+/**
+ * Legacy's count, "[N objects, M monuments]", over what matched: a results
+ * spec's `summary`. A monument is a record of type `monument`; everything
+ * else counts as an object.
+ */
+export function objectsAndMonumentsSummary({ matching, t }) {
+  let objects = 0
+  let monuments = 0
+  for (const item of matching ?? []) {
+    if (item.type === 'monument') monuments++
+    else objects++
+  }
+  return [
+    { label: t('catalogue.results.objectsFound'), count: objects },
+    { label: t('catalogue.results.monumentsFound'), count: monuments },
+  ]
+}

package/src/catalogue/fieldSearch.js

@@ -0,0 +1,176 @@
+import { computed, ref } from 'vue'
+import { useI18n } from '../i18n/index.js'
+import { combineExpansions, countryExpansion, glossaryExpansion, useKeywordIndex } from './keywordIndex.js'
+
+// The field search of the legacy `database.php` form — keyword rows, each
+// naming a field, folded with AND/OR — which the three standalone products
+// each wired for themselves (inventory-app#2037): the fields' haystacks, the
+// field options and their labels, the rows the query string carries, the
+// "searched for" line, the index. `useKeywordIndex`'s `fields` grammar is
+// the engine; this is the rest of the machinery around it, written once.
+
+/**
+ * What each field of the form searches, field for field as legacy's form
+ * did. `text` is the record's translation in the search language, English
+ * behind it. `keyword` and `location` also carry the record's `country_id`:
+ * `countryExpansion` turns a typed country name into its id, and a field is
+ * only found by that expansion if its haystack carries the id.
+ *
+ * `dynastyLabel(id)` turns on the `dynasty` field — Islamic Art's form has
+ * it, Baroque Art's and Sharing History's do not.
+ */
+export function searchFields({ dynastyLabel } = {}) {
+  const fields = {
+    keyword: (item, text) => [
+      text.name ?? item.internal_name, text.alternate_name, text.description, item.country_id, ...(item.tags ?? []),
+    ],
+    name: (item, text) => text.name ?? item.internal_name,
+    location: (item, text) => [text.location, item.country_id],
+    provenance: (item, text) => text.provenance,
+    patron: (item, text) => text.patrons ?? text.initial_owner,
+    artist: (item, text) => [...(item.artist_names ?? []), text.architects],
+    material: (item, text) => text.type,
+    // The catch-all across the descriptive fields the others leave out.
+    other: (item, text) => [
+      text.description, text.method_for_datation, text.method_for_provenance, text.obtention,
+      text.bibliography, text.workshop, text.scriber, text.binding_desc, text.history,
+    ],
+  }
+  if (dynastyLabel) fields.dynasty = (item) => (item.dynasty_ids ?? []).map(dynastyLabel)
+  return fields
+}
+
+// Every field of the form, in legacy's order, with its entry name.
+const FIELD_OPTIONS = [
+  { key: 'keyword', label: 'catalogue.field.keywords' },
+  { key: 'name', label: 'sheet.field.name' },
+  { key: 'location', label: 'sheet.field.location' },
+  { key: 'provenance', label: 'sheet.field.provenance' },
+  { key: 'dynasty', label: 'catalogue.facet.periodDynasty' },
+  { key: 'patron', label: 'catalogue.field.patron' },
+  { key: 'artist', label: 'catalogue.field.artist' },
+  { key: 'material', label: 'catalogue.field.material' },
+  { key: 'other', label: 'catalogue.field.other' },
+]
+
+/**
+ * The options of the form's field select — `[{ key, label }]`, `label` an
+ * entry name, in legacy's order — for the fields `fields` carries: what
+ * `SearchFormView`'s `fields` takes.
+ */
+export function searchFieldOptions(fields) {
+  return FIELD_OPTIONS.filter((option) => option.key in fields)
+}
+
+/** One field's label, resolved: `key` is what the query string carries. */
+export function searchFieldLabel(key, t) {
+  switch (key) {
+    case 'keyword': return t('catalogue.field.keywords')
+    case 'name': return t('sheet.field.name')
+    case 'location': return t('sheet.field.location')
+    case 'provenance': return t('sheet.field.provenance')
+    case 'dynasty': return t('catalogue.facet.periodDynasty')
+    case 'patron': return t('catalogue.field.patron')
+    case 'artist': return t('catalogue.field.artist')
+    case 'material': return t('catalogue.field.material')
+    case 'other': return t('catalogue.field.other')
+    default: return key
+  }
+}
+
+/**
+ * The same options resolved, `[{ value, label }]`, for a select a site draws
+ * itself — the results page's refine row.
+ */
+export function useSearchFieldOptions(fields) {
+  const { t } = useI18n()
+  return computed(() => searchFieldOptions(fields).map((option) => ({ value: option.key, label: searchFieldLabel(option.key, t) })))
+}
+
+/**
+ * The keyword rows the query string carries: `q`/`field` for the first
+ * (`SearchFormView`'s own, unnumbered), `qN`/`fieldN`/`opN` for the next —
+ * three from the entrance, a fourth for the results page's refine row.
+ * A row with no field searches `keyword`; with no operator, AND.
+ */
+export function searchRows(filters, count = 4) {
+  const rows = []
+  for (let n = 1; n <= count; n++) {
+    rows.push({
+      keyword: n === 1 ? filters.q : filters[`q${n}`],
+      field: (n === 1 ? filters.field : filters[`field${n}`]) || 'keyword',
+      cond: n === 1 ? 'AND' : filters[`op${n}`] || 'AND',
+    })
+  }
+  return rows
+}
+
+/** The query keys `searchRows` reads, for a results spec's `keys`. */
+export function searchRowKeys(count = 4) {
+  const keys = ['q', 'field']
+  for (let n = 2; n <= count; n++) keys.push(`q${n}`, `field${n}`, `op${n}`)
+  return keys
+}
+
+/**
+ * What was searched, spelled out: `Name: "bowl"`, `AND Location: "Cairo"`,
+ * the years, the search language, then the site's own `extras` —
+ * `(filters, t) => string` each, an empty string for nothing. Legacy's
+ * recap line, never just a count, so a visitor who scrolls past the form
+ * still reads what for.
+ */
+export function searchedFor(filters, t, { rows = 4, extras = [] } = {}) {
+  const parts = searchRows(filters, rows)
+    .filter((row) => row.keyword)
+    .map((row, i) => `${i > 0 ? `${row.cond} ` : ''}${searchFieldLabel(row.field, t)}: "${row.keyword}"`)
+  if (filters.from) parts.push(`${t('catalogue.filter.from')} ${filters.from}`)
+  if (filters.to) parts.push(`${t('catalogue.filter.to')} ${filters.to}`)
+  if (filters.lang) parts.push(`${t('catalogue.search.language')}: ${String(filters.lang).toUpperCase()}`)
+  for (const extra of extras) {
+    const part = extra(filters, t)
+    if (part) parts.push(part)
+  }
+  return parts
+}
+
+/**
+ * The results page's summary: what was searched (`searchedFor`), or "all
+ * items" for an empty query, then the count. `options` is `searchedFor`'s.
+ */
+export function searchSummary({ filters, t, pageInfo }, options = {}) {
+  const parts = searchedFor(filters, t, options)
+  return [
+    { label: t('catalogue.search.summary'), value: parts.length ? parts.join(' · ') : t('catalogue.results.allItems') },
+    { label: t('catalogue.results.itemsFound'), count: pageInfo.total },
+  ]
+}
+
+/**
+ * The index behind the results page: one long-lived `useKeywordIndex` over
+ * `entity` (`fields` grammar, legacy's `rank: 'hits'` order, the glossary
+ * and country expansions of `database_results.php`), its search language
+ * kept in step with the query's `lang`. `narrow(list, filters)` is a results
+ * spec's `narrow`: the matches in rank order, kept to what `list` (the
+ * records the spec's `scope` let through) carries. Pass `sort: false` to the
+ * spec, so the rank order stands.
+ */
+export function useFieldSearch({
+  fields,
+  entity = 'items',
+  rows = 4,
+  rank = 'hits',
+  expand = combineExpansions(glossaryExpansion(), countryExpansion()),
+} = {}) {
+  const language = ref('')
+  const index = useKeywordIndex(entity, { grammar: 'fields', fields, language, rank, expand })
+
+  function narrow(list, filters) {
+    language.value = filters.lang || ''
+    const matches = index.search(searchRows(filters, rows))
+    if (!list) return matches
+    const allowed = new Set(list.map((record) => record.id))
+    return matches.filter((record) => allowed.has(record.id))
+  }
+
+  return { narrow, index }
+}

package/src/conventions.js

@@ -108,13 +108,16 @@ function seeded(seed) {
  * among those with an image when `withImage` is set (the default), among
  * all when none has one. Null until the entity is loaded. The pick is made
  * once per visit and again only when the records change; `seed` makes it
- * deterministic.
+ * deterministic. `filter(record)` narrows the candidates first — the site's
+ * own visible rule, since this reads the raw entity (Sharing History's
+ * hidden illustrations, `display_status: 'N'`, must never be picked).
  */
-export function useFeaturedRecord(entity, { withImage = true, seed, images = 'images' } = {}) {
+export function useFeaturedRecord(entity, { withImage = true, seed, images = 'images', filter } = {}) {
   const records = entityRef(entity)
   const random = seed == null ? Math.random : seeded(seed)
   return computed(() => {
-    const all = toValue(records) ?? []
+    const loaded = toValue(records)
+    const all = filter ? (loaded ?? []).filter(filter) : loaded ?? []
     if (all.length === 0) return null
     const pool = withImage ? all.filter((record) => (record?.[images]?.length ?? 0) > 0) : all
     const candidates = pool.length > 0 ? pool : all

package/src/index.js

@@ -1,6 +1,13 @@
 export { createViewer } from './createViewer.js'
 export { createStandardViewer } from './createStandardViewer.js'
 export { useCatalogueData } from './composables/useCatalogueData.js'
+export {
+  CATALOGUE_DATE_MODE, CATALOGUE_PAGE_SIZE, objectsAndMonumentsSummary, useCatalogue,
+} from './catalogue/catalogue.js'
+export {
+  searchFieldLabel, searchFieldOptions, searchFields, searchRowKeys, searchRows, searchSummary, searchedFor,
+  useFieldSearch, useSearchFieldOptions,
+} from './catalogue/fieldSearch.js'
 export { useDataPackage } from './composables/useDataPackage.js'
 export { byId, entityRef, loadEntities, useEntities } from './composables/useEntities.js'
 export { resolveRecordLanguage, useRecordLanguage } from './composables/useRecordLanguage.js'

package/src/record/partners.js

@@ -118,14 +118,10 @@ const byDisplayOrder = (a, b) => (a?.display_order ?? 0) - (b?.display_order ??
 
 /**
  * The contact persons in legacy order (person 1 first), keeping only those
- * with a name or a title — legacy printed a person block only then. Reads
- * `contact_persons`; a package built before that list existed carries
- * `contact_person_1`/`_2` instead (inventory-app#2007 removes them).
+ * with a name or a title — legacy printed a person block only then.
  */
 function contactPersons(partner) {
-  const list = Array.isArray(partner?.contact_persons)
-    ? partner.contact_persons
-    : [partner?.contact_person_1, partner?.contact_person_2]
+  const list = Array.isArray(partner?.contact_persons) ? partner.contact_persons : []
   return list
     .filter((person) => person && (person.name || person.title))
     .map((person) => ({