ochre-sdk 1.3.2 → 1.3.4

package/dist/fetchers/container-items.mjs

@@ -2,7 +2,7 @@ import { requestOchre } from "./request.mjs";
 import { parseRequestedLanguages, resolveContentLanguages } from "../parsers/languages.mjs";
 import { parseSetItems } from "../parsers/index.mjs";
 import { XMLSetItemsData } from "../xml/schemas.mjs";
-import { stringLiteral } from "../xquery.mjs";
+import { getContentLanguage, stringLiteral } from "../xquery.mjs";
 import { compileContainerItemsQuery } from "../query.mjs";
 //#region src/fetchers/container-items.ts
 function hasArray(items) {
@@ -149,6 +149,7 @@ async function fetchContainerItems(parameters) {
 			scopeUuids,
 			belongsToCollectionScopeUuids,
 			queries,
+			contentLanguage: getContentLanguage(options),
 			body: ({ items, omitSupplemental }) => `  let $totalCount := count(${items})
   ${buildOrderedItemsClause(sort)}
   let $pagedItems := subsequence($orderedItems, ${startPosition}, ${pageSize})

package/dist/fetchers/gallery.mjs

@@ -4,14 +4,16 @@ import { gallerySchema } from "../schemas.mjs";
 import { parseRequestedLanguages, resolveContentLanguages } from "../parsers/languages.mjs";
 import { parseGallery } from "../parsers/index.mjs";
 import { XMLGalleryData } from "../xml/schemas.mjs";
-import { OCHRE_RESPONSE_PADDING, compileOchreQuery, stringLiteral } from "../xquery.mjs";
+import { OCHRE_RESPONSE_PADDING, compileOchreQuery, getContentLanguage, stringLiteral } from "../xquery.mjs";
 import * as v from "valibot";
 //#region src/fetchers/gallery.ts
 function buildXQuery(parameters) {
-	const { uuid, filter, page, perPage } = parameters;
+	const { uuid, filter, page, perPage, contentLanguage } = parameters;
 	const start = (page - 1) * perPage + 1;
 	const filterLiteral = stringLiteral(filter?.trim() ?? "");
-	return compileOchreQuery({ body: ({ omitSupplemental }) => `<ochre>${OCHRE_RESPONSE_PADDING}{
+	return compileOchreQuery({
+		contentLanguage,
+		body: ({ omitSupplemental }) => `<ochre>${OCHRE_RESPONSE_PADDING}{
   for $q in doc()/ochre[@uuid=${stringLiteral(uuid)}]
   let $filter := ${filterLiteral}
   let $resources := $q//items/resource
@@ -27,7 +29,8 @@ function buildXQuery(parameters) {
       subsequence($filtered, ${start}, ${perPage})
     )`)}
   }</gallery>
-}</ochre>` });
+}</ochre>`
+	});
 }
 async function fetchGallery(parameters, options) {
 	try {
@@ -38,7 +41,8 @@ async function fetchGallery(parameters, options) {
 				uuid,
 				filter,
 				page,
-				perPage
+				perPage,
+				contentLanguage: getContentLanguage(options)
 			}),
 			schema: XMLGalleryData,
 			label: "OCHRE gallery",

package/dist/fetchers/item-children.mjs

@@ -5,13 +5,14 @@ import { uuidSchema } from "../schemas.mjs";
 import { parseRequestedLanguages, resolveContentLanguages } from "../parsers/languages.mjs";
 import { parseLinkedItems } from "../parsers/index.mjs";
 import { XMLItemLinksData } from "../xml/schemas.mjs";
-import { OCHRE_RESPONSE_PADDING, compileOchreQuery, stringLiteral } from "../xquery.mjs";
+import { OCHRE_RESPONSE_PADDING, compileOchreQuery, getContentLanguage, stringLiteral } from "../xquery.mjs";
 import * as v from "valibot";
 //#region src/fetchers/item-children.ts
-function buildXQuery(uuid, category) {
+function buildXQuery(uuid, category, contentLanguage) {
 	const categories = category == null ? OCHRE_COLLECTION_CATEGORIES : typeof category === "string" ? [category] : category;
 	const collectionQueries = Array.from(categories, (possibleCategory) => `cts:search(fn:collection("ochre/${possibleCategory}")/ochre, $uuid-query)`);
 	return compileOchreQuery({
+		contentLanguage,
 		declarations: [`declare function local:item-children($nodes as node()*) as node()* {
   for $node in $nodes
   return
@@ -59,7 +60,7 @@ async function fetchItemChildren(uuid, options) {
 		const parsedUuid = v.parse(uuidSchema, uuid);
 		const requestedLanguages = parseRequestedLanguages(options?.languages);
 		const output = await requestOchre({
-			xquery: buildXQuery(parsedUuid, options?.category),
+			xquery: buildXQuery(parsedUuid, options?.category, getContentLanguage(options)),
 			schema: XMLItemLinksData,
 			label: "OCHRE item children",
 			options

package/dist/fetchers/item-links.mjs

@@ -5,7 +5,7 @@ import { uuidSchema } from "../schemas.mjs";
 import { parseRequestedLanguages, resolveContentLanguages } from "../parsers/languages.mjs";
 import { parseLinkedItems } from "../parsers/index.mjs";
 import { XMLItemLinksData } from "../xml/schemas.mjs";
-import { OCHRE_RESPONSE_PADDING, compileOchreQuery, stringLiteral } from "../xquery.mjs";
+import { OCHRE_RESPONSE_PADDING, compileOchreQuery, getContentLanguage, stringLiteral } from "../xquery.mjs";
 import * as v from "valibot";
 //#region src/fetchers/item-links.ts
 /**
@@ -14,7 +14,7 @@ import * as v from "valibot";
 * @param uuid - The UUID of the OCHRE item whose links should be fetched
 * @returns An XQuery string
 */
-function buildXQuery(uuid) {
+function buildXQuery(uuid, contentLanguage) {
 	const linkedItems = `for $link at $position in $link-nodes
       let $uuid := $link/@uuid/string()
       let $category := name($link)
@@ -24,7 +24,9 @@ function buildXQuery(uuid) {
 		return `if (${ITEM_CATEGORY_ALIASES[category].map((alias) => `$category = ${stringLiteral(alias)}`).join(" or ")}) then fn:collection("ochre/${category}")/ochre/${category}[@uuid = $uuid]`;
 	}).join("\n        else ")}
         else ()`;
-	return compileOchreQuery({ body: ({ omitSupplemental }) => `<ochre>${OCHRE_RESPONSE_PADDING}{let $item-uuid := ${stringLiteral(uuid)}
+	return compileOchreQuery({
+		contentLanguage,
+		body: ({ omitSupplemental }) => `<ochre>${OCHRE_RESPONSE_PADDING}{let $item-uuid := ${stringLiteral(uuid)}
 
 let $source-items := (
 ${OCHRE_COLLECTION_CATEGORIES.map((category) => `  fn:collection("ochre/${category}")/ochre[@uuid = $item-uuid]/${category}`).join(",\n")}
@@ -39,14 +41,15 @@ let $link-nodes := (
 return
     <items>{
       ${omitSupplemental(linkedItems)}
-    }</items>}</ochre>` });
+    }</items>}</ochre>`
+	});
 }
 async function fetchItemLinks(uuid, options) {
 	try {
 		const parsedUuid = v.parse(uuidSchema, uuid);
 		const requestedLanguages = parseRequestedLanguages(options?.languages);
 		const output = await requestOchre({
-			xquery: buildXQuery(parsedUuid),
+			xquery: buildXQuery(parsedUuid, getContentLanguage(options)),
 			schema: XMLItemLinksData,
 			label: "OCHRE item links",
 			options

package/dist/fetchers/item.mjs

@@ -5,7 +5,7 @@ import { uuidSchema } from "../schemas.mjs";
 import { parseRequestedLanguages } from "../parsers/languages.mjs";
 import { parseItem } from "../parsers/index.mjs";
 import { XMLData } from "../xml/schemas.mjs";
-import { OCHRE_RESPONSE_PADDING, compileOchreQuery, stringLiteral } from "../xquery.mjs";
+import { OCHRE_RESPONSE_PADDING, compileOchreQuery, getContentLanguage, stringLiteral } from "../xquery.mjs";
 import { parseWebpageView } from "../parsers/website/index.mjs";
 import * as v from "valibot";
 //#region src/fetchers/item.ts
@@ -28,10 +28,11 @@ function assertItemCategoryAllowed(category, containedItemCategory) {
 * @param parameters - The parameters for the fetch
 * @param parameters.uuid - The UUID of the OCHRE item to fetch
 * @param parameters.shouldOmitEmbeddedItems - Whether to drop the embedded item hierarchy
+* @param parameters.contentLanguage - Keep only this language of every multilingual field
 * @returns An XQuery string
 */
 function buildXQuery(parameters) {
-	const { uuid, shouldOmitEmbeddedItems } = parameters;
+	const { uuid, shouldOmitEmbeddedItems, contentLanguage } = parameters;
 	const letClauses = [`let $ochre := doc(${stringLiteral(uuid)})/ochre`];
 	let itemNodesExpression = "$ochre/node()";
 	if (shouldOmitEmbeddedItems) {
@@ -46,13 +47,16 @@ ${ITEM_CATEGORIES_WITH_EMBEDDED_ITEMS.map((category) => `  $ochre/${category}`).
         else $node
     )`;
 	}
-	return compileOchreQuery({ body: ({ omitSupplemental }) => `${letClauses.join("\n")}
+	return compileOchreQuery({
+		contentLanguage,
+		body: ({ omitSupplemental }) => `${letClauses.join("\n")}
 return
   if (empty($ochre)) then <ochre>${OCHRE_RESPONSE_PADDING}</ochre>
   else element ochre {
     $ochre/@*,
     ${omitSupplemental(itemNodesExpression)}
-  }` });
+  }`
+	});
 }
 function omitEmbeddedItems(item) {
 	const { items: _items, ...itemWithoutEmbeddedItems } = item;
@@ -67,7 +71,8 @@ async function fetchItem(uuid, options) {
 		const output = await requestOchre({
 			xquery: buildXQuery({
 				uuid: parsedUuid,
-				shouldOmitEmbeddedItems
+				shouldOmitEmbeddedItems,
+				contentLanguage: getContentLanguage(options)
 			}),
 			schema: XMLData,
 			label: "OCHRE item",

package/dist/fetchers/set/item-locations.mjs

@@ -6,7 +6,7 @@ import { parseRequiredContentLike } from "../../parsers/helpers.mjs";
 import { parseRequestedLanguages, resolveContentLanguages } from "../../parsers/languages.mjs";
 import { parseCoordinates, parseIdentification } from "../../parsers/index.mjs";
 import { XMLSetItemLocationsData } from "../../xml/schemas.mjs";
-import { stringLiteral } from "../../xquery.mjs";
+import { getContentLanguage, stringLiteral } from "../../xquery.mjs";
 import { compileContainerItemsQuery } from "../../query.mjs";
 import * as v from "valibot";
 //#region src/fetchers/set/item-locations.ts
@@ -19,6 +19,7 @@ async function fetchSetItemLocations(parameters, options) {
 				scopeUuids: setScopeUuids,
 				belongsToCollectionScopeUuids,
 				queries,
+				contentLanguage: getContentLanguage(options),
 				body: ({ items }) => `  let $propertyVariableUuids := (${Array.from(propertyVariableUuids, (uuid) => stringLiteral(uuid)).join(", ")})
 
   return <items totalCount="{count(${items})}">{

package/dist/fetchers/set/property-values.mjs

@@ -48,8 +48,8 @@ function normalizePropertyValueDataType(dataType) {
 function sortPropertyValues(values) {
 	return values.toSorted((a, b) => {
 		if (a.count !== b.count) return b.count - a.count;
-		const label = a.label?.getText() ?? null;
-		const otherLabel = b.label?.getText() ?? null;
+		const label = a.label?.getText(a.label.getDefaultLanguage()) ?? null;
+		const otherLabel = b.label?.getText(b.label.getDefaultLanguage()) ?? null;
 		if (label !== otherLabel) return label?.localeCompare(otherLabel ?? "") ?? 0;
 		return a.content?.toString().localeCompare(b.content?.toString() ?? "") ?? 0;
 	});

package/dist/fetchers/website-metadata.mjs

@@ -26,7 +26,7 @@ function parseWebsiteMetadata(data, options) {
 	const websiteTree = rawOchre.tree[0];
 	if (websiteTree == null) throw new Error("Website tree not found", { cause: data });
 	const identification = parseIdentification(websiteTree.identification, options);
-	const websiteName = identification.label.getText().trim();
+	const websiteName = identification.label.getText(identification.label.getDefaultLanguage()).trim();
 	const metadataDescription = (parseStringLike(rawOchre.metadata.description) ?? "").trim();
 	const properties = parseSimplifiedProperties(websiteTree.properties, options);
 	const reader = websitePresentationReader(properties);

package/dist/getters.mjs

@@ -27,7 +27,7 @@ function withDefaultOptions(options) {
 	};
 }
 function getPropertyVariableLabel(property) {
-	return typeof property.variable.label === "string" ? property.variable.label : property.variable.label.getText();
+	return typeof property.variable.label === "string" ? property.variable.label : property.variable.label.getText(property.variable.label.getDefaultLanguage());
 }
 function hasPropertyValue(property, value) {
 	for (const candidateValue of property.values) if (deepEqual(candidateValue, value)) return true;

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { MultilingualOptions, MultilingualString, MultilingualStringEntries, MultilingualStringEntry, MultilingualStringInput, MultilingualStringJSON, MultilingualStringObject, MultilingualStringText } from "./parsers/multilingual.mjs";
-import { AccordionWebBlock, ContextTree, ContextTreeFilterLevel, ContextTreeFilterVariant, ContextTreeLevel, ContextTreeLevelItem, ProtectedWebsite, ResponsiveStyles, Scope, Style, StylesheetCategory, StylesheetItem, WebAccordionItem, WebBlock, WebBlockByLayout, WebBlockItem, WebBlockLayout, WebElement, WebElementComponent, WebElementComponentName, WebElementComponentOf, WebElementOf, WebIiifViewer, WebImage, WebLoadingVariant, WebOptions, WebSectionDisplay, WebSectionVariant, WebSidebar, WebTitle, Webpage, Website, WebsiteMetadata, WebsitePrivacy, WebsitePropertyQuery, WebsitePropertyQueryNode, WebsiteSegment, WebsiteType } from "./types/website.mjs";
+import { AccordionWebBlock, ContextTree, ContextTreeFilterLevel, ContextTreeFilterVariant, ContextTreeLevel, ContextTreeLevelItem, ProtectedWebsite, ResponsiveStyles, Scope, Style, StylesheetCategory, StylesheetItem, WebAccordionItem, WebBlock, WebBlockByLayout, WebBlockItem, WebBlockLayout, WebElement, WebElementComponent, WebElementComponentName, WebElementComponentOf, WebElementOf, WebIiifViewer, WebImage, WebLoadingVariant, WebOptions, WebRelationVariant, WebSectionDisplay, WebSectionVariant, WebSidebar, WebTitle, Webpage, Website, WebsiteMetadata, WebsitePrivacy, WebsitePropertyQuery, WebsitePropertyQueryNode, WebsiteSegment, WebsiteType } from "./types/website.mjs";
 import { AnyBibliography, AnyConcept, AnyItem, AnyPeriod, AnyPerson, AnyPropertyValue, AnyPropertyVariable, AnyResource, AnySet, AnySpatialUnit, AnyText, AnyTree, BaseItem, BaseItemLink, BelongsTo, Bibliography, BibliographyEntryInfo, BibliographyItemLink, BibliographySourceDocument, Concept, ConceptItemLink, ContainedItemCategory, ContainedItemCategoryFromOption, ContainedItemCategoryOption, Context, ContextItem, ContextItemCategory, ContextNode, Coordinates, CoordinatesSource, DictionaryUnitItemLink, EmbeddedBibliography, EmbeddedConcept, EmbeddedItem, EmbeddedPeriod, EmbeddedPerson, EmbeddedPropertyValue, EmbeddedPropertyVariable, EmbeddedResource, EmbeddedSet, EmbeddedSpatialUnit, EmbeddedText, EmbeddedTree, Event, Gallery, Heading, HeadingItemCategory, Identification, Image, ImageMap, ImageMapArea, Interpretation, Item, ItemCategory, ItemCategoryFromOption, ItemCategoryOption, ItemCategoryWithEmbeddedItems, ItemContainerCategory, ItemLink, ItemLinkCategory, ItemLinks, ItemPayloadKind, ItemProperty, ItemWithoutEmbeddedItems, LanguageCodes, License, Metadata, Note, Observation, OcrString, Period, PeriodItemLink, Person, PersonItemLink, Property, PropertyLike, PropertyRelation, PropertyValue, PropertyValueContent, PropertyValueDataType, PropertyValueItemLink, PropertyValueQueryItem, PropertyVariable, PropertyVariableItemLink, Query, QueryGroup, QueryLeaf, QueryablePropertyValueDataType, RecursiveItemCategory, Resource, ResourceItemLink, Section, Set, SetAttributeValueQueryItem, SetBibliography, SetConcept, SetItem, SetItemCategory, SetItemLink, SetItemLocation, SetItemProperty, SetItemSimplifiedProperty, SetItemsSort, SetItemsSortDirection, SetPeriod, SetResource, SetSpatialUnit, SetStyle, SetStyleProperty, SetTree, SimplifiedProperty, SpatialUnit, SpatialUnitItemLink, Text, TextItemLink, TopLevelItem, Tree, TreeItemCategory, TreeItemLink } from "./types/index.mjs";
 import { DEFAULT_PAGE_SIZE } from "./constants.mjs";
 import { fetchGallery } from "./fetchers/gallery.mjs";
@@ -16,4 +16,4 @@ import { fetchWebsite } from "./fetchers/website.mjs";
 import { PropertyOptions, PropertySelector, getLeafPropertyValues, getProperty, getPropertyValue, getPropertyValues, getUniqueProperties, getUniquePropertyVariableLabels, isPropertyMatchingFilter, normalizePropertyVariableLabel } from "./getters.mjs";
 import { flattenItemProperties } from "./helpers.mjs";
 import { defineLanguages } from "./parsers/languages.mjs";
-export { type AccordionWebBlock, type AnyBibliography, type AnyConcept, type AnyItem, type AnyPeriod, type AnyPerson, type AnyPropertyValue, type AnyPropertyVariable, type AnyResource, type AnySet, type AnySpatialUnit, type AnyText, type AnyTree, type BaseItem, type BaseItemLink, type BelongsTo, type Bibliography, type BibliographyEntryInfo, type BibliographyItemLink, type BibliographySourceDocument, type Concept, type ConceptItemLink, type ContainedItemCategory, type ContainedItemCategoryFromOption, type ContainedItemCategoryOption, type Context, type ContextItem, type ContextItemCategory, type ContextNode, type ContextTree, type ContextTreeFilterLevel, type ContextTreeFilterVariant, type ContextTreeLevel, type ContextTreeLevelItem, type Coordinates, type CoordinatesSource, DEFAULT_PAGE_SIZE, type DictionaryUnitItemLink, type EmbeddedBibliography, type EmbeddedConcept, type EmbeddedItem, type EmbeddedPeriod, type EmbeddedPerson, type EmbeddedPropertyValue, type EmbeddedPropertyVariable, type EmbeddedResource, type EmbeddedSet, type EmbeddedSpatialUnit, type EmbeddedText, type EmbeddedTree, type Event, type Gallery, type Heading, type HeadingItemCategory, type Identification, type Image, type ImageMap, type ImageMapArea, type Interpretation, type Item, type ItemCategory, type ItemCategoryFromOption, type ItemCategoryOption, type ItemCategoryWithEmbeddedItems, type ItemContainerCategory, type ItemLink, type ItemLinkCategory, type ItemLinks, type ItemPayloadKind, type ItemProperty, type ItemWithoutEmbeddedItems, type LanguageCodes, type License, type Metadata, type MultilingualOptions, MultilingualString, type MultilingualStringEntries, type MultilingualStringEntry, type MultilingualStringInput, type MultilingualStringJSON, type MultilingualStringObject, type MultilingualStringText, type Note, type Observation, type OcrString, type Period, type PeriodItemLink, type Person, type PersonItemLink, type Property, type PropertyLike, type PropertyOptions, type PropertyRelation, type PropertySelector, type PropertyValue, type PropertyValueContent, type PropertyValueDataType, type PropertyValueItemLink, type PropertyValueQueryItem, type PropertyVariable, type PropertyVariableItemLink, type ProtectedWebsite, type Query, type QueryGroup, type QueryLeaf, type QueryablePropertyValueDataType, type RecursiveItemCategory, type Resource, type ResourceItemLink, type ResponsiveStyles, type Scope, type Section, type Set, type SetAttributeValueQueryItem, type SetBibliography, type SetConcept, type SetItem, type SetItemCategory, type SetItemLink, type SetItemLocation, type SetItemProperty, type SetItemSimplifiedProperty, type SetItemsSort, type SetItemsSortDirection, type SetPeriod, type SetResource, type SetSpatialUnit, type SetStyle, type SetStyleProperty, type SetTree, type SimplifiedProperty, type SpatialUnit, type SpatialUnitItemLink, type Style, type StylesheetCategory, type StylesheetItem, type Text, type TextItemLink, type TopLevelItem, type Tree, type TreeItemCategory, type TreeItemLink, type WebAccordionItem, type WebBlock, type WebBlockByLayout, type WebBlockItem, type WebBlockLayout, type WebElement, type WebElementComponent, type WebElementComponentName, type WebElementComponentOf, type WebElementOf, type WebIiifViewer, type WebImage, type WebLoadingVariant, type WebOptions, type WebSectionDisplay, type WebSectionVariant, type WebSidebar, type WebTitle, type Webpage, type Website, type WebsiteMetadata, type WebsitePrivacy, type WebsitePropertyQuery, type WebsitePropertyQueryNode, type WebsiteSegment, type WebsiteType, defineLanguages, fetchGallery, fetchItem, fetchItemChildren, fetchItemLinks, fetchItemOcrData, fetchSetItemLocations, fetchSetItems, fetchSetPropertyValues, fetchTreeItems, fetchWebsite, fetchWebsiteMetadata, flattenItemProperties, getLeafPropertyValues, getProperty, getPropertyValue, getPropertyValues, getUniqueProperties, getUniquePropertyVariableLabels, isPropertyMatchingFilter, normalizePropertyVariableLabel };
+export { type AccordionWebBlock, type AnyBibliography, type AnyConcept, type AnyItem, type AnyPeriod, type AnyPerson, type AnyPropertyValue, type AnyPropertyVariable, type AnyResource, type AnySet, type AnySpatialUnit, type AnyText, type AnyTree, type BaseItem, type BaseItemLink, type BelongsTo, type Bibliography, type BibliographyEntryInfo, type BibliographyItemLink, type BibliographySourceDocument, type Concept, type ConceptItemLink, type ContainedItemCategory, type ContainedItemCategoryFromOption, type ContainedItemCategoryOption, type Context, type ContextItem, type ContextItemCategory, type ContextNode, type ContextTree, type ContextTreeFilterLevel, type ContextTreeFilterVariant, type ContextTreeLevel, type ContextTreeLevelItem, type Coordinates, type CoordinatesSource, DEFAULT_PAGE_SIZE, type DictionaryUnitItemLink, type EmbeddedBibliography, type EmbeddedConcept, type EmbeddedItem, type EmbeddedPeriod, type EmbeddedPerson, type EmbeddedPropertyValue, type EmbeddedPropertyVariable, type EmbeddedResource, type EmbeddedSet, type EmbeddedSpatialUnit, type EmbeddedText, type EmbeddedTree, type Event, type Gallery, type Heading, type HeadingItemCategory, type Identification, type Image, type ImageMap, type ImageMapArea, type Interpretation, type Item, type ItemCategory, type ItemCategoryFromOption, type ItemCategoryOption, type ItemCategoryWithEmbeddedItems, type ItemContainerCategory, type ItemLink, type ItemLinkCategory, type ItemLinks, type ItemPayloadKind, type ItemProperty, type ItemWithoutEmbeddedItems, type LanguageCodes, type License, type Metadata, type MultilingualOptions, MultilingualString, type MultilingualStringEntries, type MultilingualStringEntry, type MultilingualStringInput, type MultilingualStringJSON, type MultilingualStringObject, type MultilingualStringText, type Note, type Observation, type OcrString, type Period, type PeriodItemLink, type Person, type PersonItemLink, type Property, type PropertyLike, type PropertyOptions, type PropertyRelation, type PropertySelector, type PropertyValue, type PropertyValueContent, type PropertyValueDataType, type PropertyValueItemLink, type PropertyValueQueryItem, type PropertyVariable, type PropertyVariableItemLink, type ProtectedWebsite, type Query, type QueryGroup, type QueryLeaf, type QueryablePropertyValueDataType, type RecursiveItemCategory, type Resource, type ResourceItemLink, type ResponsiveStyles, type Scope, type Section, type Set, type SetAttributeValueQueryItem, type SetBibliography, type SetConcept, type SetItem, type SetItemCategory, type SetItemLink, type SetItemLocation, type SetItemProperty, type SetItemSimplifiedProperty, type SetItemsSort, type SetItemsSortDirection, type SetPeriod, type SetResource, type SetSpatialUnit, type SetStyle, type SetStyleProperty, type SetTree, type SimplifiedProperty, type SpatialUnit, type SpatialUnitItemLink, type Style, type StylesheetCategory, type StylesheetItem, type Text, type TextItemLink, type TopLevelItem, type Tree, type TreeItemCategory, type TreeItemLink, type WebAccordionItem, type WebBlock, type WebBlockByLayout, type WebBlockItem, type WebBlockLayout, type WebElement, type WebElementComponent, type WebElementComponentName, type WebElementComponentOf, type WebElementOf, type WebIiifViewer, type WebImage, type WebLoadingVariant, type WebOptions, type WebRelationVariant, type WebSectionDisplay, type WebSectionVariant, type WebSidebar, type WebTitle, type Webpage, type Website, type WebsiteMetadata, type WebsitePrivacy, type WebsitePropertyQuery, type WebsitePropertyQueryNode, type WebsiteSegment, type WebsiteType, defineLanguages, fetchGallery, fetchItem, fetchItemChildren, fetchItemLinks, fetchItemOcrData, fetchSetItemLocations, fetchSetItems, fetchSetPropertyValues, fetchTreeItems, fetchWebsite, fetchWebsiteMetadata, flattenItemProperties, getLeafPropertyValues, getProperty, getPropertyValue, getPropertyValues, getUniqueProperties, getUniquePropertyVariableLabels, isPropertyMatchingFilter, normalizePropertyVariableLabel };

package/dist/parsers/helpers.d.mts

@@ -5,6 +5,17 @@ import { XMLContent, XMLString } from "../xml/types.mjs";
 export type FetchFunction = (input: string | URL | globalThis.Request, init?: RequestInit) => Promise<Response>;
 export type FetchBaseOptions<TLanguages extends ReadonlyArray<string> | undefined = undefined> = {
   languages?: TLanguages;
+  /**
+   * Fetch only this language of every multilingual field, instead of every
+   * language OCHRE holds. A field without it keeps its `fallbackLanguage`
+   * content, else its content in any language; aliases are always kept.
+   */
+  language?: string;
+  /**
+   * The language shown for fields that have no `language` content, typically
+   * the website's default language (defaults to `"eng"`)
+   */
+  fallbackLanguage?: string;
   fetch?: FetchFunction;
   signal?: AbortSignal;
   timeoutMilliseconds?: number;

package/dist/parsers/helpers.mjs

@@ -58,15 +58,19 @@ function parseRequiredContentLike(value, options) {
 	return parseContentLike(value, options) ?? MultilingualString.empty(options.languages, { defaultLanguage: options.defaultLanguage });
 }
 function parseContentLikeText(value, options) {
-	return parseContentLike(value, options)?.getText().trim() ?? "";
+	const content = parseContentLike(value, options);
+	return content?.getText(content.getDefaultLanguage()).trim() ?? "";
 }
 function parseStringContent(value, options = FALLBACK_PARSER_OPTIONS) {
 	if (value == null) return "";
 	if (typeof value === "string") return value;
-	if (isXMLContent(value)) return parseXMLContent(value, {
-		languages: options.languages,
-		defaultLanguage: options.defaultLanguage
-	}).getText();
+	if (isXMLContent(value)) {
+		const content = parseXMLContent(value, {
+			languages: options.languages,
+			defaultLanguage: options.defaultLanguage
+		});
+		return content.getText(content.getDefaultLanguage());
+	}
 	return parseXMLString(value).text;
 }
 //#endregion

package/dist/parsers/index.mjs

@@ -457,7 +457,7 @@ function parsePropertyDataType(dataType) {
 function parsePropertyValueContent(value, options) {
 	const dataType = parsePropertyDataType(value.dataType);
 	const rawLabel = value.content != null ? parseRequiredContentLike(value, options) : value.payload != null && value.payload !== "" ? multilingualFromText(value.payload, options) : null;
-	const contentText = readPropertyValueText(value, () => rawLabel?.getText() ?? null);
+	const contentText = readPropertyValueText(value, () => rawLabel?.getText(rawLabel.getDefaultLanguage()) ?? null);
 	const common = {
 		hierarchy: {
 			isLeaf: value.inherited == null || !value.inherited,

package/dist/parsers/multilingual.d.mts

@@ -109,11 +109,11 @@ export declare class MultilingualString<T extends ReadonlyArray<string> = Readon
   /**
    * Get text in a specific language, falling back when it has none
    */
-  getText(language?: T[number]): string;
+  getText(language: T[number]): string;
   /**
    * Get rich text in a specific language, falling back when it has none
    */
-  getRichText(language?: T[number]): string;
+  getRichText(language: T[number]): string;
   /**
    * Get text in a specific language, with no fallback
    */
@@ -133,16 +133,16 @@ export declare class MultilingualString<T extends ReadonlyArray<string> = Readon
    * can carry several entries for one language, and this returns all of them
    * rather than only the primary. Each entry carries both `text` and
    * `richText`, so a caller rendering a rich field reads them from here.
-   * @param language - The language to read, or undefined for the default
+   * @param language - The language to read
    * @returns The entries, or an empty array when no language has any
    */
-  getEntries(language?: T[number]): Array<MultilingualStringEntry>;
+  getEntries(language: T[number]): Array<MultilingualStringEntry>;
   /**
    * Get the text of every entry for a language, falling back when it has none
-   * @param language - The language to read, or undefined for the default
+   * @param language - The language to read
    * @returns The texts, or an empty array when no language has any
    */
-  getTexts(language?: T[number]): Array<string>;
+  getTexts(language: T[number]): Array<string>;
   /**
    * Get the text of every entry for a language, with no fallback
    * @param language - The language to read
@@ -259,10 +259,6 @@ export declare class MultilingualString<T extends ReadonlyArray<string> = Readon
    * @returns A new multilingual string
    */
   filterEntries(shouldKeep: (entry: MultilingualStringEntry, language: T[number]) => boolean): MultilingualString<T>;
-  /**
-   * Get the string representation, using the default language
-   */
-  toString(): string;
   /**
    * Get the JSON representation
    *

package/dist/parsers/multilingual.mjs

@@ -228,7 +228,7 @@ var MultilingualString = class MultilingualString {
 	* can carry several entries for one language, and this returns all of them
 	* rather than only the primary. Each entry carries both `text` and
 	* `richText`, so a caller rendering a rich field reads them from here.
-	* @param language - The language to read, or undefined for the default
+	* @param language - The language to read
 	* @returns The entries, or an empty array when no language has any
 	*/
 	getEntries(language) {
@@ -236,7 +236,7 @@ var MultilingualString = class MultilingualString {
 	}
 	/**
 	* Get the text of every entry for a language, falling back when it has none
-	* @param language - The language to read, or undefined for the default
+	* @param language - The language to read
 	* @returns The texts, or an empty array when no language has any
 	*/
 	getTexts(language) {
@@ -423,12 +423,6 @@ var MultilingualString = class MultilingualString {
 		}, newAvailableLanguages);
 	}
 	/**
-	* Get the string representation, using the default language
-	*/
-	toString() {
-		return this.getText();
-	}
-	/**
 	* Get the JSON representation
 	*
 	* Carries `defaultLanguage`, because it is not derivable from the content:

package/dist/parsers/website/components.mjs

@@ -85,6 +85,23 @@ function parseCollectionDisplayedProperties(reader) {
 		label: value.label
 	}]);
 }
+/**
+* Parses the "customize-special" "relations" properties, each pairing the
+* property variables it links with "use-property" with a display "variant".
+*/
+function parseCollectionRelations(reader) {
+	const relations = [];
+	const relationReaders = reader.nestedAllByValue("customize-special", "relations");
+	for (const relationReader of relationReaders) {
+		const variant = relationReader.value("variant");
+		const properties = parseCollectionDisplayedProperties(relationReader) ?? [];
+		for (const property of properties) relations.push({
+			...property,
+			variant
+		});
+	}
+	return relations;
+}
 const THREE_D_VIEWER_COMPONENT_DEFAULTS = {
 	isInteractive: true,
 	isControlsDisplayed: true
@@ -261,6 +278,7 @@ function parseCollectionComponent(parameters) {
 		component: "collection",
 		linkUuids: setLinks.map((link) => link.uuid),
 		displayedProperties: parseCollectionDisplayedProperties(componentReader),
+		relations: parseCollectionRelations(componentReader),
 		...COLLECTION_PROPERTY_DEFAULTS,
 		...propertyOverrides,
 		image: {
@@ -472,9 +490,12 @@ function parseQueryComponent(parameters) {
 	}
 	if (items.length === 0) throw new Error(formatComponentError("No queries found", "query", elementResource), { cause: componentProperty });
 	const componentOptions = parseWebsiteOptions(elementResource.options, options);
-	const collectionProperties = parseCollectionPropertyOverrides(componentReader.nestedByValue("sub-component-override", "collection"));
+	const overrideReader = componentReader.nestedByValue("sub-component-override", "collection");
+	const collectionProperties = parseCollectionPropertyOverrides(overrideReader);
 	const displayedProperties = parseCollectionDisplayedProperties(componentReader);
 	if (displayedProperties != null) collectionProperties.displayedProperties = displayedProperties;
+	const relations = parseCollectionRelations(overrideReader);
+	if (relations.length > 0) collectionProperties.relations = relations;
 	return {
 		component: "query",
 		linkUuids: setLinks.map((link) => link.uuid),

package/dist/parsers/website/options.mjs

@@ -104,7 +104,7 @@ function parseWebsiteOptions(rawOptions, options) {
 	};
 	const notes = parseNotes(rawOptions?.notes, options);
 	for (const note of notes) {
-		if (note.title?.getText() !== "Title label") continue;
+		if (note.title?.getText(note.title.getDefaultLanguage()) !== "Title label") continue;
 		parsedOptions.labels.title = note.content;
 		break;
 	}

package/dist/parsers/website/properties.mjs

@@ -76,6 +76,7 @@ function parseWebsiteProperties(properties, websiteTree, sidebar, options, paren
 			isPersistentIdentifierDisplayed: parent?.itemPage.isPersistentIdentifierDisplayed ?? true,
 			iiifViewer: parent?.itemPage.iiifViewer ?? "universal-viewer"
 		},
+		relations: { variant: parent?.relations.variant ?? "list" },
 		options: {
 			contextTree: parent?.options.contextTree ?? null,
 			scopes: parent?.options.scopes ?? null,
@@ -117,7 +118,7 @@ function parseWebsiteProperties(properties, websiteTree, sidebar, options, paren
 	websiteReader.readAllUuids(returnProperties.navbar, { searchBarBoundElementUuid: "bound-element-navbar-search-bar" });
 	websiteReader.readAll(returnProperties.footer, { isDisplayed: "footer-displayed" });
 	websiteReader.readAllUuids(returnProperties.footer, { logoUuid: "footer-logo" });
-	const itemPageReader = websiteReader.nestedByValue("page-type", "item-page");
+	const itemPageReader = websiteReader.nestedByValue("customize-special", "item-page");
 	if (itemPageReader.size > 0) {
 		for (const [key, slug] of [
 			["description", "description"],
@@ -142,6 +143,7 @@ function parseWebsiteProperties(properties, websiteTree, sidebar, options, paren
 			iiifViewer: "item-page-iiif-viewer"
 		});
 	}
+	websiteReader.nestedByValue("customize-special", "relations").readAll(returnProperties.relations, { variant: "variant" });
 	if (websiteTree.options != null) {
 		const parsedOptions = parseWebsiteOptions(websiteTree.options, options);
 		returnProperties.options.scopes = (parsedOptions.scopes != null && parsedOptions.scopes.length > 0 ? parsedOptions : returnProperties.options).scopes;

package/dist/parsers/website/reader.d.mts

@@ -70,6 +70,7 @@ export declare class WebsitePresentationReader<T extends LanguageCodes> {
   readAllUuids<O extends object>(target: O, labels: Partial<Record<UuidKeys<O>, string>>): void;
   nested(label: string): WebsitePresentationReader<T>;
   nestedByValue(label: string, value: WebsitePropertyContent<T>): WebsitePresentationReader<T>;
+  nestedAllByValue(label: string, value: WebsitePropertyContent<T>): Array<WebsitePresentationReader<T>>;
   get size(): number;
 }
 export declare function websitePresentationReader<T extends LanguageCodes>(properties: ReadonlyArray<SimplifiedProperty<T>>): WebsitePresentationReader<T>;

package/dist/parsers/website/reader.mjs

@@ -103,6 +103,14 @@ var WebsitePresentationReader = class WebsitePresentationReader {
 	nestedByValue(label, value) {
 		return new WebsitePresentationReader(this.propertyByValue(label, value)?.properties ?? []);
 	}
+	nestedAllByValue(label, value) {
+		const readers = [];
+		for (const property of this.sourceProperties) if (getProperty([property], {
+			label,
+			valueContent: value
+		}) != null) readers.push(new WebsitePresentationReader(property.properties));
+		return readers;
+	}
 	get size() {
 		return this.sourceProperties.length;
 	}

package/dist/query.d.mts

@@ -1,5 +1,5 @@
 import { PropertyRelation, Query } from "./types/index.mjs";
-import { OchreQueryContext } from "./xquery.mjs";
+import { OchreContentLanguage, OchreQueryContext } from "./xquery.mjs";
 //#region src/query.d.ts
 export declare function buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids: ReadonlyArray<string>, belongsToCollectionPropertyVariableUuid: string): string | null;
 /**
@@ -75,6 +75,7 @@ export type ItemsContainer = keyof typeof ITEMS_CONTAINERS;
  * @param parameters.queries - The query tree to compile, or null to match every item
  * @param parameters.declarations - Extra prolog declarations, placed before the compiled prolog
  * @param parameters.body - Builds the body from the name of the variable holding the items
+ * @param parameters.contentLanguage - Keep only this language of every multilingual field in the result
  * @returns A complete XQuery document
  * @internal
  */
@@ -87,6 +88,7 @@ export declare function compileContainerItemsQuery(parameters: {
   body: (context: OchreQueryContext & {
     items: string;
   }) => string;
+  contentLanguage?: OchreContentLanguage | null;
 }): string;
 /**
  * Reduce a property-value facet query tree to the leaves that filter items

package/dist/query.mjs

@@ -14,32 +14,25 @@ const CTS_INCLUDES_STOP_WORDS = /* @__PURE__ */ new Set([
 const CTS_INCLUDES_TOKEN_WORD_REGEX = /^\p{L}+$/u;
 const CTS_INCLUDES_TOKEN_REGEX = /[\p{L}\p{N}*?]+/gu;
 const CTS_EXACT_TEXT_TOKEN_REGEX = /[\p{L}\p{N}]+/gu;
-const CONTENT_TARGET_CONTENT_ELEMENT_PATHS = {
-	title: [
-		"identification",
-		"label",
-		"content"
-	],
-	description: ["description", "content"],
+const CONTENT_TARGET_FIELD_ELEMENT_PATHS = {
+	title: ["identification", "label"],
+	description: ["description"],
 	image: [
 		"image",
 		"identification",
-		"label",
-		"content"
+		"label"
 	],
 	periods: [
 		"periods",
 		"period",
 		"identification",
-		"label",
-		"content"
+		"label"
 	],
 	bibliography: [
 		"bibliographies",
 		"bibliography",
 		"identification",
-		"label",
-		"content"
+		"label"
 	]
 };
 const HELPER_SEARCH_VALUE_REFERENCE = "$value";
@@ -246,36 +239,51 @@ function buildValueNotIdReferenceQuery() {
 		value: searchValue("IDREF")
 	}));
 }
-function buildRichTextContentQueryExpression(parameters) {
-	const { value, matchMode, isCaseSensitive, language } = parameters;
-	return buildAndCtsQueryExpressionInternal([buildContentLanguageQuery(language), matchMode === "exact" ? buildRichTextExactQueryExpression({
-		value,
-		isCaseSensitive,
-		language
-	}) : buildCtsWordQueryExpression({
-		value,
-		matchMode,
-		isCaseSensitive,
-		queryFamily: "text",
-		language
-	})]);
+/**
+* Match a field's `content` in a language, falling back to another language
+* only for fields that carry no content in the first one
+*
+* Placed inside the field element (a label, a note, a property value), so the
+* missing-language check is scoped to that one field. Without a distinct
+* fallback it is the single-language query this always compiled to.
+*/
+function buildLocalizedContentQueryExpression(parameters) {
+	const { language, fallbackLanguage, buildMatchQuery } = parameters;
+	function buildContentQuery(contentLanguage) {
+		return buildNestedElementQuery(["content"], buildAndCtsQueryExpressionInternal([buildContentLanguageQuery(contentLanguage), buildMatchQuery(contentLanguage)]));
+	}
+	if (fallbackLanguage == null || fallbackLanguage === language) return buildContentQuery(language);
+	return buildOrCtsQueryExpressionInternal([buildContentQuery(language), buildAndCtsQueryExpressionInternal([buildNotCtsQueryExpression(buildNestedElementQuery(["content"], buildContentLanguageQuery(language))), buildContentQuery(fallbackLanguage)])]);
 }
-function buildValueContentInnerQuery(parameters) {
-	const { language, value, matchMode, isCaseSensitive } = parameters;
-	return buildNestedElementQuery(["content"], buildRichTextContentQueryExpression({
+function buildRichTextContentQueryExpression(parameters) {
+	const { value, matchMode, isCaseSensitive, language, fallbackLanguage } = parameters;
+	return buildLocalizedContentQueryExpression({
 		language,
-		value,
-		matchMode,
-		isCaseSensitive
-	}));
+		fallbackLanguage,
+		buildMatchQuery: (contentLanguage) => matchMode === "exact" ? buildRichTextExactQueryExpression({
+			value,
+			isCaseSensitive,
+			language: contentLanguage
+		}) : buildCtsWordQueryExpression({
+			value,
+			matchMode,
+			isCaseSensitive,
+			queryFamily: "text",
+			language: contentLanguage
+		})
+	});
 }
 function buildValueContentExactInnerQuery(parameters) {
-	const { language, value, isCaseSensitive } = parameters;
-	return buildNestedElementQuery(["content"], buildAndCtsQueryExpressionInternal([buildContentLanguageQuery(language), buildCtsElementValueQueryExpression({
-		elementName: "string",
-		value,
-		isCaseSensitive
-	})]));
+	const { language, fallbackLanguage, value, isCaseSensitive } = parameters;
+	return buildLocalizedContentQueryExpression({
+		language,
+		fallbackLanguage,
+		buildMatchQuery: () => buildCtsElementValueQueryExpression({
+			elementName: "string",
+			value,
+			isCaseSensitive
+		})
+	});
 }
 function buildValueDirectTextInnerQuery(parameters) {
 	const { value, matchMode, isCaseSensitive } = parameters;
@@ -310,26 +318,23 @@ function buildValueRawValueInnerQuery(parameters) {
 	});
 }
 function buildNotesQueryExpression(parameters) {
-	const { value, matchMode, isCaseSensitive, language } = parameters;
-	return buildNestedElementQuery([
-		"notes",
-		"note",
-		"content"
-	], buildRichTextContentQueryExpression({
+	const { value, matchMode, isCaseSensitive, language, fallbackLanguage } = parameters;
+	return buildNestedElementQuery(["notes", "note"], buildRichTextContentQueryExpression({
 		value,
 		matchMode,
 		isCaseSensitive,
-		language
+		language,
+		fallbackLanguage
 	}));
 }
 function buildContentTargetQueryExpression(parameters) {
-	const { target, value, matchMode, isCaseSensitive, language } = parameters;
-	const contentElementPath = CONTENT_TARGET_CONTENT_ELEMENT_PATHS[target];
-	return buildNestedElementQuery(contentElementPath, buildRichTextContentQueryExpression({
+	const { target, value, matchMode, isCaseSensitive, language, fallbackLanguage } = parameters;
+	return buildNestedElementQuery(CONTENT_TARGET_FIELD_ELEMENT_PATHS[target], buildRichTextContentQueryExpression({
 		value,
 		matchMode,
 		isCaseSensitive,
-		language
+		language,
+		fallbackLanguage
 	}));
 }
 function buildPropertyQueryExpression(parameters) {
@@ -381,16 +386,18 @@ function buildPropertyPresenceQueryExpression(parameters) {
 	});
 }
 function buildPropertyStringQueryExpression(parameters) {
-	const { propertyVariable, propertyRelation, value, matchMode, isCaseSensitive, language } = parameters;
+	const { propertyVariable, propertyRelation, value, matchMode, isCaseSensitive, language, fallbackLanguage } = parameters;
 	return buildPropertyTextMatchQueryExpression({
 		propertyVariable,
 		propertyRelation,
 		contentQueryExpression: matchMode === "exact" ? buildValueContentExactInnerQuery({
 			language,
+			fallbackLanguage,
 			value,
 			isCaseSensitive
-		}) : buildValueContentInnerQuery({
+		}) : buildRichTextContentQueryExpression({
 			language,
+			fallbackLanguage,
 			value,
 			matchMode,
 			isCaseSensitive
@@ -429,8 +436,9 @@ function buildPropertyAllQueryExpression(parameters) {
 		propertyVariable: query.propertyVariable,
 		propertyRelation: query.propertyRelation,
 		valueFilters: [buildValueNotIdReferenceQuery()],
-		contentQueryExpression: buildValueContentInnerQuery({
+		contentQueryExpression: buildRichTextContentQueryExpression({
 			language: query.language,
+			fallbackLanguage: query.fallbackLanguage,
 			value,
 			matchMode,
 			isCaseSensitive: query.isCaseSensitive
@@ -470,18 +478,20 @@ function buildPropertyDateRangeQueryExpression(query) {
 	});
 }
 function buildItemStringQueryExpression(parameters) {
-	const { value, matchMode, isCaseSensitive, language } = parameters;
+	const { value, matchMode, isCaseSensitive, language, fallbackLanguage } = parameters;
 	return buildOrCtsQueryExpressionInternal([buildContentTargetQueryExpression({
 		target: "title",
 		value,
 		matchMode,
 		isCaseSensitive,
-		language
+		language,
+		fallbackLanguage
 	}), buildPropertyStringQueryExpression({
 		value,
 		matchMode,
 		isCaseSensitive,
-		language
+		language,
+		fallbackLanguage
 	})]);
 }
 function tokenizeOcrExactValue(value) {
@@ -614,13 +624,15 @@ function buildLeafValueQueryExpression(parameters) {
 			value,
 			matchMode,
 			isCaseSensitive: query.isCaseSensitive,
-			language: query.language
+			language: query.language,
+			fallbackLanguage: query.fallbackLanguage
 		});
 		case "notes": return buildNotesQueryExpression({
 			value,
 			matchMode,
 			isCaseSensitive: query.isCaseSensitive,
-			language: query.language
+			language: query.language,
+			fallbackLanguage: query.fallbackLanguage
 		});
 		case "title":
 		case "description":
@@ -631,7 +643,8 @@ function buildLeafValueQueryExpression(parameters) {
 			value,
 			matchMode,
 			isCaseSensitive: query.isCaseSensitive,
-			language: query.language
+			language: query.language,
+			fallbackLanguage: query.fallbackLanguage
 		});
 		case "property": switch (query.dataType) {
 			case "all": return buildPropertyAllQueryExpression({
@@ -650,7 +663,8 @@ function buildLeafValueQueryExpression(parameters) {
 				value,
 				matchMode,
 				isCaseSensitive: query.isCaseSensitive,
-				language: query.language
+				language: query.language,
+				fallbackLanguage: query.fallbackLanguage
 			});
 			case "integer":
 			case "decimal":
@@ -728,7 +742,8 @@ function getLeafHelperKey(parameters) {
 			query.target,
 			value,
 			query.isCaseSensitive ? "case-sensitive" : "case-insensitive",
-			query.language
+			query.language,
+			query.fallbackLanguage ?? ""
 		].join("|");
 		case "property": return [
 			"leaf",
@@ -739,7 +754,8 @@ function getLeafHelperKey(parameters) {
 			query.propertyRelation ?? "",
 			value,
 			query.isCaseSensitive ? "case-sensitive" : "case-insensitive",
-			query.language
+			query.language,
+			query.fallbackLanguage ?? ""
 		].join("|");
 	}
 }
@@ -775,6 +791,7 @@ function getIncludesLeafHelperKey(parameters) {
 			query.target,
 			query.isCaseSensitive ? "case-sensitive" : "case-insensitive",
 			query.language,
+			query.fallbackLanguage ?? "",
 			isWildcarded ? "wildcarded" : "unwildcarded",
 			isStemmed ? "stemmed" : "unstemmed"
 		].join("|");
@@ -786,6 +803,7 @@ function getIncludesLeafHelperKey(parameters) {
 			query.propertyRelation ?? "",
 			query.isCaseSensitive ? "case-sensitive" : "case-insensitive",
 			query.language,
+			query.fallbackLanguage ?? "",
 			isWildcarded ? "wildcarded" : "unwildcarded",
 			isStemmed ? "stemmed" : "unstemmed"
 		].join("|");
@@ -876,7 +894,7 @@ function getCompatibleIncludesGroupLeaves(query) {
 	if (!("or" in query) || query.or.length <= 1) return null;
 	const leafQueries = [];
 	for (const childQuery of query.or) {
-		if (!isQueryLeaf(childQuery) || childQuery.target === "ocr") return null;
+		if (!isQueryLeaf(childQuery) || childQuery.target === "ocr" || childQuery.fallbackLanguage != null && childQuery.fallbackLanguage !== childQuery.language) return null;
 		leafQueries.push(childQuery);
 	}
 	const firstQuery = leafQueries[0];
@@ -941,7 +959,26 @@ function buildCtsItemsPlan(queryExpression) {
 	return {
 		kind: "search",
 		itemPredicates: [],
-		queryExpressions: [queryExpression]
+		queryExpressions: [queryExpression],
+		resultPredicates: []
+	};
+}
+/**
+* Plan a leaf that falls back to a second language for fields missing the first
+*
+* The strict query needs a `cts:not-query` scoped to one field, which CTS
+* resolves against the Set's single fragment and so rules out every item the
+* moment any item holds the first language. The search therefore runs a
+* superset (the leaf in either language), and `cts:contains` then applies the
+* strict query to each matched item projection, where the negation is exact.
+*/
+function buildFallbackItemsPlan(parameters) {
+	const { supersetQueryExpression, strictQueryExpression } = parameters;
+	return {
+		kind: "search",
+		itemPredicates: [],
+		queryExpressions: [supersetQueryExpression],
+		resultPredicates: [`[cts:contains(., ${strictQueryExpression})]`]
 	};
 }
 /**
@@ -958,7 +995,8 @@ function buildNegatedItemsPlan(queryExpression) {
 	return {
 		kind: "search",
 		itemPredicates: [`[not(cts:contains(., ${queryExpression}))]`],
-		queryExpressions: []
+		queryExpressions: [],
+		resultPredicates: []
 	};
 }
 /**
@@ -976,6 +1014,9 @@ function flattenItemsPlans(childPlans, kind) {
 	}
 	return flattenedPlans;
 }
+function appendUniquePredicates(predicates, addedPredicates) {
+	for (const predicate of addedPredicates) if (!predicates.includes(predicate)) predicates.push(predicate);
+}
 /**
 * Fold the children of an `and` group into one plan
 *
@@ -987,7 +1028,8 @@ function buildAndItemsPlan(childPlans) {
 	const mergedPlan = {
 		kind: "search",
 		itemPredicates: [],
-		queryExpressions: []
+		queryExpressions: [],
+		resultPredicates: []
 	};
 	const unfoldablePlans = [];
 	for (const childPlan of flattenItemsPlans(childPlans, "intersect")) {
@@ -995,11 +1037,12 @@ function buildAndItemsPlan(childPlans) {
 			unfoldablePlans.push(childPlan);
 			continue;
 		}
-		for (const itemPredicate of childPlan.itemPredicates) if (!mergedPlan.itemPredicates.includes(itemPredicate)) mergedPlan.itemPredicates.push(itemPredicate);
+		appendUniquePredicates(mergedPlan.itemPredicates, childPlan.itemPredicates);
+		appendUniquePredicates(mergedPlan.resultPredicates, childPlan.resultPredicates);
 		mergedPlan.queryExpressions.push(...childPlan.queryExpressions);
 	}
 	if (unfoldablePlans.length === 0) return mergedPlan;
-	const intersectedPlans = mergedPlan.itemPredicates.length === 0 && mergedPlan.queryExpressions.length === 0 ? unfoldablePlans : [mergedPlan, ...unfoldablePlans];
+	const intersectedPlans = mergedPlan.itemPredicates.length === 0 && mergedPlan.queryExpressions.length === 0 && mergedPlan.resultPredicates.length === 0 ? unfoldablePlans : [mergedPlan, ...unfoldablePlans];
 	return intersectedPlans.length === 1 ? intersectedPlans[0] ?? mergedPlan : {
 		kind: "intersect",
 		children: intersectedPlans
@@ -1015,7 +1058,7 @@ function buildOrItemsPlan(childPlans) {
 	const mergedQueryExpressions = [];
 	const unionedPlans = [];
 	for (const childPlan of flattenItemsPlans(childPlans, "union")) {
-		if (childPlan.kind === "search" && childPlan.itemPredicates.length === 0) {
+		if (childPlan.kind === "search" && childPlan.itemPredicates.length === 0 && childPlan.resultPredicates.length === 0) {
 			mergedQueryExpressions.push(buildAndCtsQueryExpressionInternal(childPlan.queryExpressions));
 			continue;
 		}
@@ -1024,7 +1067,8 @@ function buildOrItemsPlan(childPlans) {
 	if (mergedQueryExpressions.length > 0) unionedPlans.unshift({
 		kind: "search",
 		itemPredicates: [],
-		queryExpressions: [buildOrCtsQueryExpressionInternal(mergedQueryExpressions)]
+		queryExpressions: [buildOrCtsQueryExpressionInternal(mergedQueryExpressions)],
+		resultPredicates: []
 	});
 	if (unionedPlans.length === 0) return buildCtsItemsPlan("cts:false-query()");
 	return unionedPlans.length === 1 ? unionedPlans[0] ?? buildCtsItemsPlan("cts:false-query()") : {
@@ -1039,11 +1083,24 @@ function buildItemsPlan(context, query) {
 			return {
 				kind: "search",
 				itemPredicates: [query.isNegated === true ? `[not(@uuid = ${bindingName})]` : `[@uuid = ${bindingName}]`],
-				queryExpressions: []
+				queryExpressions: [],
+				resultPredicates: []
 			};
 		}
 		const queryExpression = buildLeafQueryExpression(context, query);
-		return query.isNegated === true ? buildNegatedItemsPlan(queryExpression) : buildCtsItemsPlan(queryExpression);
+		if (query.isNegated === true) return buildNegatedItemsPlan(queryExpression);
+		if (query.fallbackLanguage == null || query.fallbackLanguage === query.language) return buildCtsItemsPlan(queryExpression);
+		return buildFallbackItemsPlan({
+			supersetQueryExpression: buildOrCtsQueryExpressionInternal([buildLeafQueryExpression(context, {
+				...query,
+				fallbackLanguage: void 0
+			}), buildLeafQueryExpression(context, {
+				...query,
+				language: query.fallbackLanguage,
+				fallbackLanguage: void 0
+			})]),
+			strictQueryExpression: queryExpression
+		});
 	}
 	const optimizedIncludesGroupQueries = getCompatibleIncludesGroupLeaves(query);
 	if (optimizedIncludesGroupQueries != null) return buildCtsItemsPlan(buildIncludesGroupQueryExpression(context, optimizedIncludesGroupQueries));
@@ -1062,7 +1119,8 @@ function buildItemsPlanExpression(parameters) {
 	if (plan.kind === "search") {
 		const itemsExpression = `${baseItemsExpression}${plan.itemPredicates.join("")}`;
 		const queryName = queryNamesByPlan.get(plan);
-		return queryName == null ? itemsExpression : `cts:search(${itemsExpression}, ${queryName})`;
+		const searchedExpression = queryName == null ? itemsExpression : `cts:search(${itemsExpression}, ${queryName})`;
+		return plan.resultPredicates.length === 0 ? searchedExpression : `(${searchedExpression})${plan.resultPredicates.join("")}`;
 	}
 	return `(${Array.from(plan.children, (childPlan) => buildItemsPlanExpression({
 		plan: childPlan,
@@ -1150,7 +1208,8 @@ function buildQueryPlan(parameters) {
 	const plan = queries == null ? {
 		kind: "search",
 		itemPredicates: [],
-		queryExpressions: []
+		queryExpressions: [],
+		resultPredicates: []
 	} : buildItemsPlan(context, queries);
 	const searchPlans = [];
 	collectItemsSearchPlans(plan, searchPlans);
@@ -1202,11 +1261,12 @@ function buildQueryPlan(parameters) {
 * @param parameters.queries - The query tree to compile, or null to match every item
 * @param parameters.declarations - Extra prolog declarations, placed before the compiled prolog
 * @param parameters.body - Builds the body from the name of the variable holding the items
+* @param parameters.contentLanguage - Keep only this language of every multilingual field in the result
 * @returns A complete XQuery document
 * @internal
 */
 function compileContainerItemsQuery(parameters) {
-	const { container, scopeUuids, belongsToCollectionScopeUuids, queries, declarations = [], body } = parameters;
+	const { container, scopeUuids, belongsToCollectionScopeUuids, queries, declarations = [], body, contentLanguage } = parameters;
 	const { scopeVariable, itemsExpression } = ITEMS_CONTAINERS[container];
 	const plan = buildQueryPlan({
 		queries,
@@ -1225,7 +1285,8 @@ ${body({
 			...context,
 			items: plan.itemsVariable
 		})}
-}</ochre>`
+}</ochre>`,
+		contentLanguage
 	});
 }
 /**

package/dist/schemas.mjs

@@ -84,6 +84,7 @@ const standardQueryFields = {
 	matchMode: v.picklist(["includes", "exact"]),
 	isCaseSensitive: v.boolean(),
 	language: defaultString("eng"),
+	fallbackLanguage: v.optional(v.string()),
 	isNegated: defaultBoolean(false)
 };
 const propertyRelationSchema = v.picklist(["related", "inverse"]);

package/dist/types/index.d.mts

@@ -853,6 +853,10 @@ export type SetItemsSort = {
  * layer holds a single OCR word, so `includes` matches every search term as its
  * own word and `exact` matches the terms as an adjacent run of whole words. OCR
  * text carries no language, so `ocr` leaves take no `language`.
+ *
+ * `fallbackLanguage` searches a field in that language only when the field has
+ * no content in `language`, so a match follows the text a reader of `language`
+ * is shown. Leave it unset to search `language` alone.
  */
 export type QueryLeaf = {
   target: "property";
@@ -865,6 +869,7 @@ export type QueryLeaf = {
   matchMode: "includes" | "exact";
   isCaseSensitive: boolean;
   language: string;
+  fallbackLanguage?: string;
   isNegated?: boolean;
 } | {
   target: "property";
@@ -877,6 +882,7 @@ export type QueryLeaf = {
   matchMode: "includes" | "exact";
   isCaseSensitive: boolean;
   language: string;
+  fallbackLanguage?: string;
   isNegated?: boolean;
 } | {
   target: "property";
@@ -889,6 +895,7 @@ export type QueryLeaf = {
   matchMode: "includes" | "exact";
   isCaseSensitive: boolean;
   language: string;
+  fallbackLanguage?: string;
   isNegated?: boolean;
 } | {
   target: "property";
@@ -901,6 +908,7 @@ export type QueryLeaf = {
   matchMode: "includes" | "exact";
   isCaseSensitive: boolean;
   language: string;
+  fallbackLanguage?: string;
   isNegated?: boolean;
 } | {
   target: "property";
@@ -911,6 +919,7 @@ export type QueryLeaf = {
   matchMode: "includes" | "exact";
   isCaseSensitive: boolean;
   language: string;
+  fallbackLanguage?: string;
   isNegated?: boolean;
 } | {
   target: "string";
@@ -918,6 +927,7 @@ export type QueryLeaf = {
   matchMode: "includes" | "exact";
   isCaseSensitive: boolean;
   language: string;
+  fallbackLanguage?: string;
   isNegated?: boolean;
 } | {
   target: "ocr";
@@ -931,6 +941,7 @@ export type QueryLeaf = {
   matchMode: "includes" | "exact";
   isCaseSensitive: boolean;
   language: string;
+  fallbackLanguage?: string;
   isNegated?: boolean;
 };
 /**

package/dist/types/website.d.mts

@@ -87,6 +87,10 @@ export type WebLoadingVariant = "spinner" | "skeleton" | "animation" | "none";
  * How an item page groups a repeated section
  */
 export type WebSectionVariant = "discrete" | "tabs-horizontal" | "tabs-vertical" | "tabular";
+/**
+ * How a website displays an item's related items
+ */
+export type WebRelationVariant = "list" | "dropdown-list" | "grid" | "gallery" | "inline";
 /**
  * The IIIF viewer a website renders images with
  */
@@ -206,6 +210,9 @@ export type Website<T extends LanguageCodes = LanguageCodes> = {
       isPersistentIdentifierDisplayed: boolean;
       iiifViewer: WebIiifViewer;
     };
+    relations: {
+      variant: WebRelationVariant;
+    };
     options: Prettify<WebOptions<T> & {
       stylesheets: {
         properties: Array<StylesheetItem>;
@@ -336,6 +343,11 @@ export type WebElementComponent<T extends LanguageCodes = LanguageCodes> = {
     uuid: string;
     label: MultilingualString<T> | null;
   }> | null;
+  relations: Array<{
+    uuid: string;
+    label: MultilingualString<T> | null;
+    variant: WebRelationVariant | null;
+  }>;
   variant: "slide" | "table" | "card" | "tile" | "showcase";
   paginationVariant: "default" | "numeric";
   loadingVariant: WebLoadingVariant;

package/dist/xquery.d.mts

@@ -17,6 +17,25 @@ export declare function stringLiteral(value: string): string;
  * @internal
  */
 export declare const OCHRE_RESPONSE_PADDING = "<!--ochre-sdk: keeps an empty result distinct from a failed query-->";
+/**
+ * Which language a query should return, and what to show where it is missing
+ */
+export type OchreContentLanguage = {
+  language: string;
+  fallbackLanguage: string;
+};
+/**
+ * Resolve the content language a fetch asked for
+ * @param options - The fetch options
+ * @param options.language - The language to keep
+ * @param options.fallbackLanguage - The language shown where `language` is missing
+ * @returns The content language, or null to keep every language
+ * @internal
+ */
+export declare function getContentLanguage(options?: {
+  language?: string;
+  fallbackLanguage?: string;
+}): OchreContentLanguage | null;
 /**
  * What a query body can ask the surrounding document for
  *
@@ -47,11 +66,13 @@ export type OchreQueryContext = {
  * @param parameters - The document parameters
  * @param parameters.declarations - Prolog declarations, emitted in order before the supplemental helper
  * @param parameters.body - Builds the query body
+ * @param parameters.contentLanguage - Keep only this language of every multilingual field in the result
  * @returns A complete XQuery document
  * @internal
  */
 export declare function compileOchreQuery(parameters: {
   declarations?: ReadonlyArray<string>;
   body: (context: OchreQueryContext) => string;
+  contentLanguage?: OchreContentLanguage | null;
 }): string;
 //#endregion

package/dist/xquery.mjs

@@ -1,3 +1,4 @@
+import { DEFAULT_LANGUAGES } from "./constants.mjs";
 //#region src/xquery.ts
 /**
 * Build a string literal for an XQuery string
@@ -46,6 +47,63 @@ const SUPPLEMENTAL_XQUERY_PROLOG = `declare function local:omit-supplemental($no
       }
     else $node
 };`;
+/**
+* XQuery prolog declaring `local:select-language`, which keeps one language of
+* every multilingual field in a node sequence
+*
+* A field's `content` children are reduced to the one in `$language`, else the
+* one in `$fallback`, else the first in any language, which is the choice the
+* API's own `lang` parameter makes. `zxx` content is always kept, since it holds
+* a field's aliases rather than a translation; the API's `lang` parameter drops
+* it, which is why the SDK selects languages itself. Leaf elements are
+* returned by reference; testing for multilingual descendants before copying a
+* subtree measured slower than copying it.
+*/
+const LANGUAGE_XQUERY_PROLOG = `declare function local:select-language($nodes as node()*, $language as xs:string, $fallback as xs:string) as node()* {
+  for $node in $nodes
+  return
+    typeswitch ($node)
+    case element() return
+      if (empty($node/*))
+      then $node
+      else
+        let $contents := $node/content[@xml:lang]
+        let $selected :=
+          if (empty($contents))
+          then ()
+          else (
+            $contents[@xml:lang = $language],
+            $contents[@xml:lang = $fallback],
+            $contents[@xml:lang != "zxx"]
+          )[1]
+        return element { node-name($node) } {
+          $node/@*,
+          for $child in $node/node()
+          return
+            if ($child instance of element(content) and exists($child/@xml:lang))
+            then
+              if ($child is $selected or $child/@xml:lang = "zxx")
+              then $child
+              else ()
+            else local:select-language($child, $language, $fallback)
+        }
+    default return $node
+};`;
+/**
+* Resolve the content language a fetch asked for
+* @param options - The fetch options
+* @param options.language - The language to keep
+* @param options.fallbackLanguage - The language shown where `language` is missing
+* @returns The content language, or null to keep every language
+* @internal
+*/
+function getContentLanguage(options) {
+	if (options?.language == null) return null;
+	return {
+		language: options.language,
+		fallbackLanguage: options.fallbackLanguage ?? DEFAULT_LANGUAGES[0]
+	};
+}
 const NOT_SUPPLEMENTAL_PREDICATE = "[not(ancestor-or-self::*[@supplemental = \"true\"])]";
 /**
 * Compile a complete XQuery document for the OCHRE API
@@ -57,21 +115,27 @@ const NOT_SUPPLEMENTAL_PREDICATE = "[not(ancestor-or-self::*[@supplemental = \"t
 * @param parameters - The document parameters
 * @param parameters.declarations - Prolog declarations, emitted in order before the supplemental helper
 * @param parameters.body - Builds the query body
+* @param parameters.contentLanguage - Keep only this language of every multilingual field in the result
 * @returns A complete XQuery document
 * @internal
 */
 function compileOchreQuery(parameters) {
-	const { declarations = [], body } = parameters;
-	return `${[
+	const { declarations = [], body, contentLanguage } = parameters;
+	const prologDeclarations = [
 		"xquery version \"1.0-ml\";",
 		...declarations,
-		SUPPLEMENTAL_XQUERY_PROLOG
-	].join("\n\n")}
-
-${body({
+		SUPPLEMENTAL_XQUERY_PROLOG,
+		...contentLanguage == null ? [] : [LANGUAGE_XQUERY_PROLOG]
+	];
+	const bodyExpression = body({
 		omitSupplemental: (expression) => `local:omit-supplemental(${expression})`,
 		notSupplemental: NOT_SUPPLEMENTAL_PREDICATE
-	})}`;
+	});
+	return `${prologDeclarations.join("\n\n")}
+
+${contentLanguage == null ? bodyExpression : `local:select-language((
+${bodyExpression}
+), ${stringLiteral(contentLanguage.language)}, ${stringLiteral(contentLanguage.fallbackLanguage)})`}`;
 }
 //#endregion
-export { OCHRE_RESPONSE_PADDING, compileOchreQuery, stringLiteral };
+export { OCHRE_RESPONSE_PADDING, compileOchreQuery, getContentLanguage, stringLiteral };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ochre-sdk",
-  "version": "1.3.2",
+  "version": "1.3.4",
   "type": "module",
   "license": "MIT",
   "description": "Node.js library for working with OCHRE (Online Cultural and Historical Research Environment) data",
@@ -45,20 +45,20 @@
     "dist"
   ],
   "dependencies": {
-    "fast-equals": "^6.0.4",
+    "fast-equals": "^6.1.0",
     "fast-xml-parser": "^5.11.2",
     "valibot": "^1.5.0"
   },
   "devDependencies": {
     "@antfu/eslint-config": "^9.5.1",
-    "@types/node": "^24.19.0",
+    "@types/node": "^24.19.1",
     "bumpp": "^12.3.0",
-    "eslint": "^10.11.0",
+    "eslint": "^10.12.0",
     "eslint-plugin-erasable-syntax-only": "^0.7.2",
     "eslint-plugin-slop": "^0.1.3",
     "eslint-plugin-sonarjs": "^4.2.2",
     "knip": "^6.39.0",
-    "oxfmt": "^0.71.0",
+    "oxfmt": "^0.72.0",
     "tsdown": "^0.23.0",
     "typescript": "^6.0.3",
     "vitest": "^5.0.3"