ochre-sdk 1.1.0 → 1.1.2

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import { MultilingualOptions, MultilingualString, MultilingualStringEntries, MultilingualStringEntry, MultilingualStringInput, MultilingualStringJSON, MultilingualStringObject, MultilingualStringText } from "./parsers/multilingual.mjs";
-import { ContextTree, ContextTreeFilterLevel, ContextTreeFilterVariant, ContextTreeLevel, ContextTreeLevelItem, ProtectedWebsite, ResponsiveStyles, Scope, Style, 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 { BaseItem, BaseItemLink, BelongsTo, Bibliography, BibliographyEntryInfo, BibliographyItemLink, BibliographySourceDocument, Concept, ConceptItemLink, ContainedItemCategory, ContainedItemCategoryFromOption, ContainedItemCategoryOption, Context, ContextItem, ContextItemCategory, ContextNode, Coordinates, CoordinatesSource, DictionaryUnitItemLink, Event, Gallery, Heading, HeadingItemCategory, Identification, Image, ImageMap, ImageMapArea, Interpretation, Item, ItemCategory, ItemCategoryFromOption, ItemCategoryOption, ItemCategoryWithEmbeddedItems, ItemContainerCategory, ItemLink, ItemLinkCategory, ItemLinks, ItemPayloadKind, 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, Resource, ResourceItemLink, Section, Set, SetAttributeValueQueryItem, SetBibliography, SetConcept, SetItem, SetItemCategory, SetItemLink, SetItemProperty, SetItemSimplifiedProperty, SetItemsSort, SetItemsSortDirection, SetPeriod, SetResource, SetSpatialUnit, SetTree, SimplifiedProperty, SpatialUnit, SpatialUnitItemLink, Text, TextItemLink, Tree, TreeItemCategory, TreeItemLink } from "./types/index.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 { 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, SetItemProperty, SetItemSimplifiedProperty, SetItemsSort, SetItemsSortDirection, SetPeriod, SetResource, SetSpatialUnit, 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";
 import { fetchItemChildren } from "./fetchers/item-children.mjs";
@@ -9,9 +9,10 @@ import { fetchItemOcrData } from "./fetchers/item-ocr-data.mjs";
 import { fetchItem } from "./fetchers/item.mjs";
 import { fetchSetItems } from "./fetchers/set/items.mjs";
 import { fetchSetPropertyValues } from "./fetchers/set/property-values.mjs";
+import { fetchTreeItems } from "./fetchers/tree/items.mjs";
 import { fetchWebsiteMetadata } from "./fetchers/website-metadata.mjs";
 import { fetchWebsite } from "./fetchers/website.mjs";
-import { PropertyOptions, PropertySelector, getProperty, getPropertyValue, getPropertyValues, getUniqueProperties, getUniquePropertyVariableLabels, isPropertyMatchingFilter, normalizePropertyVariableLabel } from "./getters.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 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 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 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 Resource, type ResourceItemLink, type ResponsiveStyles, type Scope, type Section, type Set, type SetAttributeValueQueryItem, type SetBibliography, type SetConcept, type SetItem, type SetItemCategory, type SetItemLink, type SetItemProperty, type SetItemSimplifiedProperty, type SetItemsSort, type SetItemsSortDirection, type SetPeriod, type SetResource, type SetSpatialUnit, type SetTree, type SimplifiedProperty, type SpatialUnit, type SpatialUnitItemLink, type Style, type StylesheetItem, type Text, type TextItemLink, 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, fetchSetItems, fetchSetPropertyValues, fetchWebsite, fetchWebsiteMetadata, flattenItemProperties, 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 SetItemProperty, type SetItemSimplifiedProperty, type SetItemsSort, type SetItemsSortDirection, type SetPeriod, type SetResource, type SetSpatialUnit, 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, fetchSetItems, fetchSetPropertyValues, fetchTreeItems, fetchWebsite, fetchWebsiteMetadata, flattenItemProperties, getLeafPropertyValues, getProperty, getPropertyValue, getPropertyValues, getUniqueProperties, getUniquePropertyVariableLabels, isPropertyMatchingFilter, normalizePropertyVariableLabel };

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { DEFAULT_PAGE_SIZE } from "./constants.mjs";
-import { getProperty, getPropertyValue, getPropertyValues, getUniqueProperties, getUniquePropertyVariableLabels, isPropertyMatchingFilter, normalizePropertyVariableLabel } from "./getters.mjs";
+import { getLeafPropertyValues, getProperty, getPropertyValue, getPropertyValues, getUniqueProperties, getUniquePropertyVariableLabels, isPropertyMatchingFilter, normalizePropertyVariableLabel } from "./getters.mjs";
 import { flattenItemProperties } from "./helpers.mjs";
 import { MultilingualString } from "./parsers/multilingual.mjs";
 import { defineLanguages } from "./parsers/languages.mjs";
@@ -10,6 +10,7 @@ import { fetchItemOcrData } from "./fetchers/item-ocr-data.mjs";
 import { fetchItem } from "./fetchers/item.mjs";
 import { fetchSetItems } from "./fetchers/set/items.mjs";
 import { fetchSetPropertyValues } from "./fetchers/set/property-values.mjs";
+import { fetchTreeItems } from "./fetchers/tree/items.mjs";
 import { fetchWebsiteMetadata } from "./fetchers/website-metadata.mjs";
 import { fetchWebsite } from "./fetchers/website.mjs";
-export { DEFAULT_PAGE_SIZE, MultilingualString, defineLanguages, fetchGallery, fetchItem, fetchItemChildren, fetchItemLinks, fetchItemOcrData, fetchSetItems, fetchSetPropertyValues, fetchWebsite, fetchWebsiteMetadata, flattenItemProperties, getProperty, getPropertyValue, getPropertyValues, getUniqueProperties, getUniquePropertyVariableLabels, isPropertyMatchingFilter, normalizePropertyVariableLabel };
+export { DEFAULT_PAGE_SIZE, MultilingualString, defineLanguages, fetchGallery, fetchItem, fetchItemChildren, fetchItemLinks, fetchItemOcrData, fetchSetItems, fetchSetPropertyValues, fetchTreeItems, fetchWebsite, fetchWebsiteMetadata, flattenItemProperties, getLeafPropertyValues, getProperty, getPropertyValue, getPropertyValues, getUniqueProperties, getUniquePropertyVariableLabels, isPropertyMatchingFilter, normalizePropertyVariableLabel };

package/dist/parsers/multilingual.d.mts

@@ -126,6 +126,29 @@ export declare class MultilingualString<T extends ReadonlyArray<string> = Readon
    * Get every entry for a specific language, with no fallback
    */
   getExactEntries(language: T[number]): Array<MultilingualStringEntry>;
+  /**
+   * Get every entry for a language, falling back when it has none
+   *
+   * The multi-entry counterpart of {@link MultilingualString.getText}: OCHRE
+   * 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
+   * @returns The entries, or an empty array when no language has any
+   */
+  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
+   * @returns The texts, or an empty array when no language has any
+   */
+  getTexts(language?: T[number]): Array<string>;
+  /**
+   * Get the text of every entry for a language, with no fallback
+   * @param language - The language to read
+   * @returns The texts, or an empty array when that language has none
+   */
+  getExactTexts(language: T[number]): Array<string>;
   /**
    * Get the alias values OCHRE carries as `zxx` content
    */
@@ -138,6 +161,46 @@ export declare class MultilingualString<T extends ReadonlyArray<string> = Readon
    * Get the language reads fall back to before trying the rest
    */
   getDefaultLanguage(): T[number];
+  /**
+   * Get every language this string was built to hold
+   *
+   * The configured language list, which is not the same question as
+   * {@link MultilingualString.getAvailableLanguages}: that one answers which
+   * languages actually carry content, and is a subset of this.
+   * @returns The supported languages
+   */
+  getSupportedLanguages(): Array<T[number]>;
+  /**
+   * Whether any language carries an entry
+   *
+   * Answers the structural question. A language whose only entry is blank
+   * still counts here; {@link MultilingualString.hasContent} is the question
+   * about text. Aliases are not entries, so a string carrying only aliases is
+   * empty by this measure and {@link MultilingualString.hasAliases} is true.
+   * @returns True when no language carries an entry
+   */
+  isEmpty(): boolean;
+  /**
+   * Whether any entry in any language carries text that is not whitespace
+   *
+   * Deliberately not the negation of {@link MultilingualString.isEmpty}, which
+   * only asks whether entries exist. OCHRE does serve fields holding a single
+   * whitespace entry, so a caller deciding whether to render something wants
+   * this one, and it looks at every entry rather than only the primary.
+   * @returns True when some entry has non-whitespace text
+   */
+  hasContent(): boolean;
+  /**
+   * Whether a specific language carries an entry, with no fallback
+   * @param language - The language to test
+   * @returns True when that language carries at least one entry
+   */
+  hasLanguage(language: T[number]): boolean;
+  /**
+   * Whether OCHRE carried any `zxx` alias values for this string
+   * @returns True when there is at least one alias
+   */
+  hasAliases(): boolean;
   /**
    * Set the text for a language, or append another entry to it
    * @param language - The language to write
@@ -158,6 +221,44 @@ export declare class MultilingualString<T extends ReadonlyArray<string> = Readon
    * @returns A new multilingual string
    */
   without(language: T[number]): MultilingualString<T>;
+  /**
+   * Replace the alias values
+   *
+   * Aliases are the `zxx` content OCHRE carries alongside a field's languages,
+   * so they are set as a whole rather than per language. Empty strings are
+   * dropped, matching how they are read from a payload.
+   * @param aliases - The aliases to carry
+   * @returns A new multilingual string
+   */
+  withAliases(aliases: ReadonlyArray<string>): MultilingualString<T>;
+  /**
+   * Transform the text of every entry in every language
+   *
+   * Replaces the old `map`, which corrupted rich text: it wrote the
+   * transformed plain text and left the entry's `richText` to be re-derived,
+   * so a transform such as uppercasing turned `<InternalLink uuid="abc">` into
+   * markup OCHRE never wrote. The transform here runs against plain text only,
+   * and the entry's rich text is rebuilt from the result, so the two can never
+   * disagree.
+   *
+   * A transform that needs to keep or rewrite markup returns
+   * `{ text, richText }` instead of a string, and both are used verbatim.
+   * @param transform - Produces the new text for one entry
+   * @returns A new multilingual string
+   */
+  mapText(transform: (text: string, language: T[number]) => MultilingualStringInput): MultilingualString<T>;
+  /**
+   * Keep only the entries a predicate accepts
+   *
+   * The callback receives the whole entry rather than just its text, so it
+   * can also test `richText` and `isPrimary`. Dropping every entry of a
+   * language removes that language, and when that was the default the default
+   * moves to the first language that still has content, so reads keep
+   * resolving.
+   * @param shouldKeep - Whether to keep one entry
+   * @returns A new multilingual string
+   */
+  filterEntries(shouldKeep: (entry: MultilingualStringEntry, language: T[number]) => boolean): MultilingualString<T>;
   /**
    * Get the string representation, using the default language
    */

package/dist/parsers/multilingual.mjs

@@ -222,6 +222,35 @@ var MultilingualString = class MultilingualString {
 		return Array.from(this.resolveEntries(language, true), (entry) => ({ ...entry }));
 	}
 	/**
+	* Get every entry for a language, falling back when it has none
+	*
+	* The multi-entry counterpart of {@link MultilingualString.getText}: OCHRE
+	* 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
+	* @returns The entries, or an empty array when no language has any
+	*/
+	getEntries(language) {
+		return Array.from(this.resolveEntries(language, false), (entry) => ({ ...entry }));
+	}
+	/**
+	* 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
+	* @returns The texts, or an empty array when no language has any
+	*/
+	getTexts(language) {
+		return Array.from(this.resolveEntries(language, false), (entry) => entry.text);
+	}
+	/**
+	* Get the text of every entry for a language, with no fallback
+	* @param language - The language to read
+	* @returns The texts, or an empty array when that language has none
+	*/
+	getExactTexts(language) {
+		return Array.from(this.resolveEntries(language, true), (entry) => entry.text);
+	}
+	/**
 	* Get the alias values OCHRE carries as `zxx` content
 	*/
 	getAliases() {
@@ -240,6 +269,60 @@ var MultilingualString = class MultilingualString {
 		return this._options.defaultLanguage;
 	}
 	/**
+	* Get every language this string was built to hold
+	*
+	* The configured language list, which is not the same question as
+	* {@link MultilingualString.getAvailableLanguages}: that one answers which
+	* languages actually carry content, and is a subset of this.
+	* @returns The supported languages
+	*/
+	getSupportedLanguages() {
+		return [...this._options.availableLanguages];
+	}
+	/**
+	* Whether any language carries an entry
+	*
+	* Answers the structural question. A language whose only entry is blank
+	* still counts here; {@link MultilingualString.hasContent} is the question
+	* about text. Aliases are not entries, so a string carrying only aliases is
+	* empty by this measure and {@link MultilingualString.hasAliases} is true.
+	* @returns True when no language carries an entry
+	*/
+	isEmpty() {
+		return this._availableLanguages.length === 0;
+	}
+	/**
+	* Whether any entry in any language carries text that is not whitespace
+	*
+	* Deliberately not the negation of {@link MultilingualString.isEmpty}, which
+	* only asks whether entries exist. OCHRE does serve fields holding a single
+	* whitespace entry, so a caller deciding whether to render something wants
+	* this one, and it looks at every entry rather than only the primary.
+	* @returns True when some entry has non-whitespace text
+	*/
+	hasContent() {
+		for (const language of this._availableLanguages) {
+			const entries = this._content[language] ?? [];
+			for (const entry of entries) if (entry.text.trim() !== "") return true;
+		}
+		return false;
+	}
+	/**
+	* Whether a specific language carries an entry, with no fallback
+	* @param language - The language to test
+	* @returns True when that language carries at least one entry
+	*/
+	hasLanguage(language) {
+		return (this._content[language]?.length ?? 0) > 0;
+	}
+	/**
+	* Whether OCHRE carried any `zxx` alias values for this string
+	* @returns True when there is at least one alias
+	*/
+	hasAliases() {
+		return this._aliases.length > 0;
+	}
+	/**
 	* Set the text for a language, or append another entry to it
 	* @param language - The language to write
 	* @param text - The text to write
@@ -274,6 +357,72 @@ var MultilingualString = class MultilingualString {
 		}, newAvailableLanguages);
 	}
 	/**
+	* Replace the alias values
+	*
+	* Aliases are the `zxx` content OCHRE carries alongside a field's languages,
+	* so they are set as a whole rather than per language. Empty strings are
+	* dropped, matching how they are read from a payload.
+	* @param aliases - The aliases to carry
+	* @returns A new multilingual string
+	*/
+	withAliases(aliases) {
+		return MultilingualString.fromNormalized(cloneContent(this._content), {
+			...this._options,
+			aliases: normalizeAliases(aliases)
+		}, this._availableLanguages);
+	}
+	/**
+	* Transform the text of every entry in every language
+	*
+	* Replaces the old `map`, which corrupted rich text: it wrote the
+	* transformed plain text and left the entry's `richText` to be re-derived,
+	* so a transform such as uppercasing turned `<InternalLink uuid="abc">` into
+	* markup OCHRE never wrote. The transform here runs against plain text only,
+	* and the entry's rich text is rebuilt from the result, so the two can never
+	* disagree.
+	*
+	* A transform that needs to keep or rewrite markup returns
+	* `{ text, richText }` instead of a string, and both are used verbatim.
+	* @param transform - Produces the new text for one entry
+	* @returns A new multilingual string
+	*/
+	mapText(transform) {
+		const newContent = {};
+		for (const language of this._availableLanguages) {
+			const currentEntries = this._content[language] ?? [];
+			newContent[language] = normalizePrimary(Array.from(currentEntries, (entry) => ({
+				...normalizeInputText(transform(entry.text, language)),
+				isPrimary: entry.isPrimary
+			})));
+		}
+		return MultilingualString.fromNormalized(newContent, this._options, this._availableLanguages);
+	}
+	/**
+	* Keep only the entries a predicate accepts
+	*
+	* The callback receives the whole entry rather than just its text, so it
+	* can also test `richText` and `isPrimary`. Dropping every entry of a
+	* language removes that language, and when that was the default the default
+	* moves to the first language that still has content, so reads keep
+	* resolving.
+	* @param shouldKeep - Whether to keep one entry
+	* @returns A new multilingual string
+	*/
+	filterEntries(shouldKeep) {
+		const newContent = {};
+		for (const language of this._availableLanguages) {
+			const currentEntries = this._content[language] ?? [];
+			const entries = [];
+			for (const entry of currentEntries) if (shouldKeep({ ...entry }, language)) entries.push({ ...entry });
+			newContent[language] = normalizePrimary(entries);
+		}
+		const newAvailableLanguages = getLanguagesWithEntries(newContent, this._options.availableLanguages);
+		return MultilingualString.fromNormalized(newContent, {
+			...this._options,
+			defaultLanguage: newAvailableLanguages.includes(this._options.defaultLanguage) ? this._options.defaultLanguage : resolveDefaultLanguageOption(newAvailableLanguages, this._options.availableLanguages)
+		}, newAvailableLanguages);
+	}
+	/**
 	* Get the string representation, using the default language
 	*/
 	toString() {

package/dist/query.d.mts

@@ -2,12 +2,38 @@ import { PropertyRelation, Query } from "./types/index.mjs";
 import { OchreQueryContext } from "./xquery.mjs";
 //#region src/query.d.ts
 export declare function buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids: ReadonlyArray<string>, belongsToCollectionPropertyVariableUuid: string): string | null;
+/**
+ * The scope variable and searchable path of each item container
+ *
+ * A path has to stay inline in `cts:search`: binding it to a variable first
+ * materializes the sequence and makes every query `XDMP-UNSEARCHABLE`, even a
+ * plain word query. Each references its own scope variable, which
+ * {@link compileContainerItemsQuery} declares.
+ *
+ * A Tree nests its items under headings to any depth, so its path walks the
+ * descendant axis and then keeps only the nodes a heading or `items` holds
+ * directly, which is what distinguishes an item from the elements inside one.
+ * Excluding `heading` matters twice: a heading is not an item, and searching
+ * over headings would match every item under a heading whose own text matches.
+ * The union form `items/(* | heading/*)` is deliberately not used, because
+ * MarkLogic rejects a union as `XDMP-UNSEARCHABLE`.
+ */
+declare const ITEMS_CONTAINERS: {
+  readonly set: {
+    readonly scopeVariable: "$setScopeUuids";
+    readonly itemsExpression: "doc()/ochre/set[@uuid = $setScopeUuids]/items/*";
+  };
+  readonly tree: {
+    readonly scopeVariable: "$treeScopeUuids";
+    readonly itemsExpression: "doc()/ochre/tree[@uuid = $treeScopeUuids]/items/descendant::*[not(self::heading)][parent::items or parent::heading]";
+  };
+};
 /**
  * Compile a query tree into the clauses that bind the matching Set items
  *
  * The returned `itemsClause` binds {@link ITEMS_VARIABLE} and has to be placed
  * inside an XQuery body, with `prolog` declared ahead of it.
- * {@link compileSetItemsQuery} does both and is what fetchers should use;
+ * {@link compileContainerItemsQuery} does both and is what fetchers should use;
  * this is exposed for tests that assert on the compiled CTS.
  * @param parameters - The plan parameters
  * @param parameters.queries - The query tree to compile, or null to match every item
@@ -30,15 +56,21 @@ export declare function buildQueryPlan(parameters: {
   }>;
 };
 /**
- * Compile a Set item query into a complete XQuery document
+ * The OCHRE item containers a paginated item query can run over
+ */
+export type ItemsContainer = keyof typeof ITEMS_CONTAINERS;
+/**
+ * Compile an item query over a Set or a Tree into a complete XQuery document
  *
  * Owns everything a caller would otherwise have to know and restate: the
- * version declaration, the Set scope variable, the supplemental-stripping
- * prolog, the inline searchable path, where the compiled helper prolog goes and
- * that it is only declared when non-empty, the `<ochre>` wrapper, and the name
- * of the variable holding the matching items. The body receives that name.
+ * version declaration, the scope variable, the supplemental-stripping prolog,
+ * the inline searchable path for the container, where the compiled helper
+ * prolog goes and that it is only declared when non-empty, the `<ochre>`
+ * wrapper, and the name of the variable holding the matching items. The body
+ * receives that name, so it is identical for either container.
  * @param parameters - The query parameters
- * @param parameters.setScopeUuids - The Set scope UUIDs to search within
+ * @param parameters.container - Whether the scope UUIDs name Sets or Trees
+ * @param parameters.scopeUuids - The container UUIDs to search within
  * @param parameters.belongsToCollectionScopeUuids - Collection scope UUIDs to narrow to
  * @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
@@ -46,8 +78,9 @@ export declare function buildQueryPlan(parameters: {
  * @returns A complete XQuery document
  * @internal
  */
-export declare function compileSetItemsQuery(parameters: {
-  setScopeUuids: ReadonlyArray<string>;
+export declare function compileContainerItemsQuery(parameters: {
+  container: ItemsContainer;
+  scopeUuids: ReadonlyArray<string>;
   belongsToCollectionScopeUuids: ReadonlyArray<string>;
   queries: Query | null;
   declarations?: ReadonlyArray<string>;

package/dist/query.mjs

@@ -1111,22 +1111,38 @@ function buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids,
 * @returns The prolog declaring the query helpers, and the `let` clauses binding `$items`
 */
 const ITEMS_VARIABLE = "$items";
-const SET_SCOPE_VARIABLE = "$setScopeUuids";
 /**
-* The XQuery path a Set item search runs over
+* The scope variable and searchable path of each item container
 *
-* The path has to stay inline in `cts:search`: binding it to a variable first
+* A path has to stay inline in `cts:search`: binding it to a variable first
 * materializes the sequence and makes every query `XDMP-UNSEARCHABLE`, even a
-* plain word query. It references {@link SET_SCOPE_VARIABLE}, which
-* {@link compileSetItemsQuery} declares.
+* plain word query. Each references its own scope variable, which
+* {@link compileContainerItemsQuery} declares.
+*
+* A Tree nests its items under headings to any depth, so its path walks the
+* descendant axis and then keeps only the nodes a heading or `items` holds
+* directly, which is what distinguishes an item from the elements inside one.
+* Excluding `heading` matters twice: a heading is not an item, and searching
+* over headings would match every item under a heading whose own text matches.
+* The union form `items/(* | heading/*)` is deliberately not used, because
+* MarkLogic rejects a union as `XDMP-UNSEARCHABLE`.
 */
-const SET_ITEMS_EXPRESSION = `doc()/ochre/set[@uuid = ${SET_SCOPE_VARIABLE}]/items/*`;
+const ITEMS_CONTAINERS = {
+	set: {
+		scopeVariable: "$setScopeUuids",
+		itemsExpression: "doc()/ochre/set[@uuid = $setScopeUuids]/items/*"
+	},
+	tree: {
+		scopeVariable: "$treeScopeUuids",
+		itemsExpression: "doc()/ochre/tree[@uuid = $treeScopeUuids]/items/descendant::*[not(self::heading)][parent::items or parent::heading]"
+	}
+};
 /**
 * Compile a query tree into the clauses that bind the matching Set items
 *
 * The returned `itemsClause` binds {@link ITEMS_VARIABLE} and has to be placed
 * inside an XQuery body, with `prolog` declared ahead of it.
-* {@link compileSetItemsQuery} does both and is what fetchers should use;
+* {@link compileContainerItemsQuery} does both and is what fetchers should use;
 * this is exposed for tests that assert on the compiled CTS.
 * @param parameters - The plan parameters
 * @param parameters.queries - The query tree to compile, or null to match every item
@@ -1178,15 +1194,17 @@ function buildQueryPlan(parameters) {
 	};
 }
 /**
-* Compile a Set item query into a complete XQuery document
+* Compile an item query over a Set or a Tree into a complete XQuery document
 *
 * Owns everything a caller would otherwise have to know and restate: the
-* version declaration, the Set scope variable, the supplemental-stripping
-* prolog, the inline searchable path, where the compiled helper prolog goes and
-* that it is only declared when non-empty, the `<ochre>` wrapper, and the name
-* of the variable holding the matching items. The body receives that name.
+* version declaration, the scope variable, the supplemental-stripping prolog,
+* the inline searchable path for the container, where the compiled helper
+* prolog goes and that it is only declared when non-empty, the `<ochre>`
+* wrapper, and the name of the variable holding the matching items. The body
+* receives that name, so it is identical for either container.
 * @param parameters - The query parameters
-* @param parameters.setScopeUuids - The Set scope UUIDs to search within
+* @param parameters.container - Whether the scope UUIDs name Sets or Trees
+* @param parameters.scopeUuids - The container UUIDs to search within
 * @param parameters.belongsToCollectionScopeUuids - Collection scope UUIDs to narrow to
 * @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
@@ -1194,17 +1212,18 @@ function buildQueryPlan(parameters) {
 * @returns A complete XQuery document
 * @internal
 */
-function compileSetItemsQuery(parameters) {
-	const { setScopeUuids, belongsToCollectionScopeUuids, queries, declarations = [], body } = parameters;
+function compileContainerItemsQuery(parameters) {
+	const { container, scopeUuids, belongsToCollectionScopeUuids, queries, declarations = [], body } = parameters;
+	const { scopeVariable, itemsExpression } = ITEMS_CONTAINERS[container];
 	const plan = buildQueryPlan({
 		queries,
-		baseItemsExpression: SET_ITEMS_EXPRESSION,
+		baseItemsExpression: itemsExpression,
 		scopeQueryExpression: buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids, BELONGS_TO_COLLECTION_UUID)
 	});
 	return compileOchreQuery({
 		declarations: [
 			...declarations,
-			`declare variable ${SET_SCOPE_VARIABLE} := (${Array.from(setScopeUuids, (uuid) => stringLiteral(uuid)).join(", ")});`,
+			`declare variable ${scopeVariable} := (${Array.from(scopeUuids, (uuid) => stringLiteral(uuid)).join(", ")});`,
 			...plan.prolog === "" ? [] : [plan.prolog]
 		],
 		body: (context) => `<ochre>{
@@ -1268,4 +1287,4 @@ function getPropertyFacetSelectors(queries) {
 	return selectors.values().toArray();
 }
 //#endregion
-export { buildBelongsToCollectionQueryExpression, buildQueryPlan, compileSetItemsQuery, getItemFilterQueries, getPropertyFacetSelectors };
+export { buildBelongsToCollectionQueryExpression, buildQueryPlan, compileContainerItemsQuery, getItemFilterQueries, getPropertyFacetSelectors };

package/dist/schemas.d.mts

@@ -65,12 +65,32 @@ export declare const itemOcrDataParametersSchema: v.ObjectSchema<{
   readonly matchMode: v.OptionalSchema<v.PicklistSchema<["includes", "exact"], undefined>, "includes">;
   readonly isCaseSensitive: v.GenericSchema<unknown, boolean>;
 }, undefined>;
-/**
- * Schema for validating Set items parameters
- * @internal
- */
 export declare const setItemsParametersSchema: v.ObjectSchema<{
+  readonly belongsToCollectionScopeUuids: v.OptionalSchema<v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.CheckAction<string, "Invalid pseudo-UUID">]>, undefined>, readonly []>;
+  readonly queries: v.OptionalSchema<v.NullableSchema<v.GenericSchema<unknown, Query>, undefined>, null>;
+  readonly sort: v.OptionalSchema<v.VariantSchema<"target", [v.StrictObjectSchema<{
+    readonly target: v.LiteralSchema<"none", undefined>;
+  }, undefined>, v.StrictObjectSchema<{
+    readonly target: v.LiteralSchema<"title", undefined>;
+    readonly direction: v.OptionalSchema<v.PicklistSchema<["asc", "desc"], undefined>, "asc">;
+    readonly language: v.GenericSchema<unknown, string>;
+  }, undefined>, v.StrictObjectSchema<{
+    readonly target: v.LiteralSchema<"date", undefined>;
+    readonly direction: v.OptionalSchema<v.PicklistSchema<["asc", "desc"], undefined>, "asc">;
+  }, undefined>, v.StrictObjectSchema<{
+    readonly target: v.LiteralSchema<"propertyValue", undefined>;
+    readonly propertyVariableUuid: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.CheckAction<string, "Invalid pseudo-UUID">]>;
+    readonly dataType: v.PicklistSchema<readonly ["string", "integer", "decimal", "boolean", "date", "dateTime", "time", "IDREF"], undefined>;
+    readonly direction: v.OptionalSchema<v.PicklistSchema<["asc", "desc"], undefined>, "asc">;
+    readonly language: v.GenericSchema<unknown, string>;
+  }, undefined>], undefined>, {
+    readonly target: "none";
+  }>;
+  readonly page: v.OptionalSchema<v.GenericSchema<unknown, number>, 1>;
+  readonly pageSize: v.OptionalSchema<v.GenericSchema<unknown, number>, 48>;
   readonly setScopeUuids: v.SchemaWithPipe<readonly [v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.CheckAction<string, "Invalid pseudo-UUID">]>, undefined>, v.MinLengthAction<string[], 1, "At least one set scope UUID is required">]>;
+}, undefined>;
+export declare const treeItemsParametersSchema: v.ObjectSchema<{
   readonly belongsToCollectionScopeUuids: v.OptionalSchema<v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.CheckAction<string, "Invalid pseudo-UUID">]>, undefined>, readonly []>;
   readonly queries: v.OptionalSchema<v.NullableSchema<v.GenericSchema<unknown, Query>, undefined>, null>;
   readonly sort: v.OptionalSchema<v.VariantSchema<"target", [v.StrictObjectSchema<{
@@ -79,6 +99,9 @@ export declare const setItemsParametersSchema: v.ObjectSchema<{
     readonly target: v.LiteralSchema<"title", undefined>;
     readonly direction: v.OptionalSchema<v.PicklistSchema<["asc", "desc"], undefined>, "asc">;
     readonly language: v.GenericSchema<unknown, string>;
+  }, undefined>, v.StrictObjectSchema<{
+    readonly target: v.LiteralSchema<"date", undefined>;
+    readonly direction: v.OptionalSchema<v.PicklistSchema<["asc", "desc"], undefined>, "asc">;
   }, undefined>, v.StrictObjectSchema<{
     readonly target: v.LiteralSchema<"propertyValue", undefined>;
     readonly propertyVariableUuid: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.CheckAction<string, "Invalid pseudo-UUID">]>;
@@ -90,5 +113,6 @@ export declare const setItemsParametersSchema: v.ObjectSchema<{
   }>;
   readonly page: v.OptionalSchema<v.GenericSchema<unknown, number>, 1>;
   readonly pageSize: v.OptionalSchema<v.GenericSchema<unknown, number>, 48>;
+  readonly treeScopeUuids: v.SchemaWithPipe<readonly [v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.CheckAction<string, "Invalid pseudo-UUID">]>, undefined>, v.MinLengthAction<string[], 1, "At least one tree scope UUID is required">]>;
 }, undefined>;
 //#endregion

package/dist/schemas.mjs

@@ -195,6 +195,10 @@ const setItemsSortSchema = v.optional(v.variant("target", [
 		direction: sortDirectionSchema,
 		language: defaultString("eng")
 	}),
+	v.strictObject({
+		target: v.literal("date"),
+		direction: sortDirectionSchema
+	}),
 	v.strictObject({
 		target: v.literal("propertyValue"),
 		propertyVariableUuid: uuidSchema,
@@ -243,13 +247,20 @@ const itemOcrDataParametersSchema = v.object({
 * Schema for validating Set items parameters
 * @internal
 */
-const setItemsParametersSchema = v.object({
-	setScopeUuids: v.pipe(v.array(uuidSchema), v.minLength(1, "At least one set scope UUID is required")),
+const containerItemsParametersEntries = {
 	belongsToCollectionScopeUuids: v.optional(v.array(uuidSchema), []),
 	queries: setQueriesSchema,
 	sort: setItemsSortSchema,
 	page: v.optional(positiveNumber("Page must be positive"), 1),
 	pageSize: v.optional(positiveNumber("Page size must be positive"), 48)
+};
+const setItemsParametersSchema = v.object({
+	setScopeUuids: v.pipe(v.array(uuidSchema), v.minLength(1, "At least one set scope UUID is required")),
+	...containerItemsParametersEntries
+});
+const treeItemsParametersSchema = v.object({
+	treeScopeUuids: v.pipe(v.array(uuidSchema), v.minLength(1, "At least one tree scope UUID is required")),
+	...containerItemsParametersEntries
 });
 //#endregion
-export { componentSchema, gallerySchema, isPseudoUuid, iso639_3Schema, itemOcrDataParametersSchema, renderOptionsSchema, setItemsParametersSchema, setPropertyValuesParametersSchema, uuidSchema };
+export { componentSchema, gallerySchema, isPseudoUuid, iso639_3Schema, itemOcrDataParametersSchema, renderOptionsSchema, setItemsParametersSchema, setPropertyValuesParametersSchema, treeItemsParametersSchema, uuidSchema };