ochre-sdk 1.0.72 → 1.0.74

package/dist/query.mjs

@@ -12,11 +12,6 @@ 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;
-/**
-* Error message for OCR queries nested inside an OR group
-* @internal
-*/
-const OCR_DISJUNCTION_ERROR_MESSAGE = "OCR queries cannot be nested inside an OR group because they are resolved by a document join instead of a CTS query";
 const CONTENT_TARGET_CONTENT_ELEMENT_PATHS = {
 	title: [
 		"identification",
@@ -204,9 +199,6 @@ function buildNestedElementQuery(elementNames, queryExpression) {
 function buildNotCtsQueryExpression(queryExpression) {
 	return `cts:not-query(${queryExpression})`;
 }
-function buildCtsNearQueryExpression(queryExpressions) {
-	return `cts:near-query((${queryExpressions.join(", ")}), ${queryExpressions.length - 1}, ("ordered"))`;
-}
 function buildAndCtsQueryExpressionInternal(queryExpressions) {
 	if (queryExpressions.length === 0) return "cts:true-query()";
 	if (queryExpressions.length === 1) return queryExpressions[0] ?? "cts:true-query()";
@@ -480,62 +472,81 @@ function buildItemStringQueryExpression(parameters) {
 		language
 	})]);
 }
-function tokenizeOcrSearchValue(parameters) {
-	const { value, matchMode, isCaseSensitive } = parameters;
-	const rawTerms = (isCaseSensitive ? value : value.toLowerCase()).match(matchMode === "exact" ? CTS_EXACT_TEXT_TOKEN_REGEX : CTS_INCLUDES_TOKEN_REGEX) ?? [];
+function tokenizeOcrPhraseValue(value) {
 	const terms = [];
-	for (const term of rawTerms) if (getWildcardStrippedValue(term) !== "") terms.push(term);
+	for (const term of value.split(/\s+/u)) if (term !== "") terms.push(term);
 	return terms;
 }
 /**
-* Compile one CTS query expression per OCR search term, in word order
+* Word queries against the OCR layer cannot carry a stemming option: the OCHRE
+* database has unstemmed word searches turned off, and asking an element word
+* query for `unstemmed` fails with `XDMP-WORDSEARCH`. Omitting the option
+* altogether resolves the term against the database default instead.
+*/
+function buildOcrWordQueryExpression(parameters) {
+	const { value, isCaseSensitive } = parameters;
+	const options = [
+		isCaseSensitive ? "case-sensitive" : "case-insensitive",
+		"diacritic-insensitive",
+		"punctuation-insensitive",
+		"whitespace-insensitive"
+	];
+	if (hasWildcardCharacters(value)) options.push("wildcarded");
+	return `cts:element-word-query(xs:QName("string"), ${stringLiteral(value)}, (${options.map((option) => stringLiteral(option)).join(", ")}))`;
+}
+/**
+* Compile an OCR text search into a query over the `<ocr>` layer of a Resource
+* document
 *
-* Highlighting matches each OCR word against these same per-term expressions,
-* so hit locations always agree with what the filter matched.
-* @internal
+* Every `<string>` node in that layer holds a single OCR word, so `includes`
+* matches each search term as its own word anywhere in the layer, and `exact`
+* matches the terms as a run of adjacent whole string values. A phrase cannot
+* be a word query here: word positions do not carry across the `<string>`
+* boundaries, which makes `cts:near-query` the only phrase mechanism, and its
+* distance is a total span rather than a pairwise gap.
 */
-function buildOcrTermQueryExpressions(parameters) {
-	const { value, matchMode, isCaseSensitive } = parameters;
-	const terms = tokenizeOcrSearchValue({
+function buildOcrQueryExpression(query) {
+	const { value, matchMode, isCaseSensitive } = query;
+	if (matchMode === "exact") {
+		const terms = tokenizeOcrPhraseValue(value);
+		if (terms.length === 0) return "cts:false-query()";
+		const termQueryExpressions = Array.from(terms, (term) => buildCtsElementValueQueryExpression({
+			elementName: "string",
+			value: term,
+			isCaseSensitive
+		}));
+		return buildNestedElementQuery(["ocr"], termQueryExpressions.length === 1 ? termQueryExpressions[0] ?? "cts:false-query()" : `cts:near-query((${termQueryExpressions.join(", ")}), ${termQueryExpressions.length - 1}, ("ordered"))`);
+	}
+	const terms = tokenizeIncludesSearchValue({
 		value,
-		matchMode,
 		isCaseSensitive
 	});
-	const isWholeWordEquality = matchMode === "exact" && terms.length === 1;
-	return Array.from(terms, (term) => isWholeWordEquality ? buildCtsElementValueQueryExpression({
-		elementName: "string",
+	if (terms.length === 0) return "cts:false-query()";
+	return buildNestedElementQuery(["ocr"], buildAndCtsQueryExpressionInternal(Array.from(terms, (term) => buildOcrWordQueryExpression({
 		value: term,
 		isCaseSensitive
-	}) : buildCtsWordQueryExpression({
-		value: term,
-		matchMode,
-		isCaseSensitive,
-		queryFamily: "text"
-	}));
+	}))));
 }
-function buildOcrQueryExpression(query) {
-	const termQueryExpressions = buildOcrTermQueryExpressions(query);
-	if (termQueryExpressions.length === 0) return "cts:false-query()";
-	return buildNestedElementQuery(["ocr"], termQueryExpressions.length > 1 ? buildCtsNearQueryExpression(termQueryExpressions) : termQueryExpressions[0] ?? "cts:false-query()");
-}
-function registerOcrItemPredicate(context, query) {
-	const bindingKey = [
+/**
+* Bind the UUIDs of the Resource documents whose OCR layer matches a query,
+* reusing the binding when the same search is requested more than once
+*/
+function registerOcrBinding(context, query) {
+	const key = [
 		query.value,
 		query.matchMode,
 		query.isCaseSensitive ? "case-sensitive" : "case-insensitive"
 	].join("|");
-	let variableName = context.ocrVariableNamesByKey.get(bindingKey);
-	if (variableName == null) {
-		variableName = `$ocrUuids${context.nextOcrSerial}`;
-		context.nextOcrSerial += 1;
-		context.ocrVariableNamesByKey.set(bindingKey, variableName);
-		context.ocrBindings.push({
-			name: variableName,
-			expression: `for $ocrDocument in cts:search(doc(), ${buildOcrQueryExpression(query)})\n    return document-uri($ocrDocument)`
-		});
-	}
-	const itemPredicate = query.isNegated === true ? `[not(@uuid = ${variableName})]` : `[@uuid = ${variableName}]`;
-	if (!context.itemPredicates.includes(itemPredicate)) context.itemPredicates.push(itemPredicate);
+	const existingName = context.ocrBindingNamesByKey.get(key);
+	if (existingName != null) return existingName;
+	const name = `$ocrItemUuids${context.ocrBindings.length + 1}`;
+	const queryExpression = buildOcrQueryExpression(query);
+	context.ocrBindingNamesByKey.set(key, name);
+	context.ocrBindings.push({
+		name,
+		expression: queryExpression === "cts:false-query()" ? "()" : `cts:search(/ochre/resource, ${queryExpression})/@uuid/string()`
+	});
+	return name;
 }
 function getLeafSearchValue(query) {
 	switch (query.target) {
@@ -618,10 +629,8 @@ function createQueryCompilerContext() {
 		nextHelperSerial: 1,
 		helperNamesByKey: /* @__PURE__ */ new Map(),
 		helperDeclarations: [],
-		nextOcrSerial: 1,
-		ocrVariableNamesByKey: /* @__PURE__ */ new Map(),
-		ocrBindings: [],
-		itemPredicates: []
+		ocrBindingNamesByKey: /* @__PURE__ */ new Map(),
+		ocrBindings: []
 	};
 }
 function registerConstantHelper(parameters) {
@@ -818,19 +827,6 @@ function getQueryGroupChildren(query) {
 function getQueryGroupOperator(query) {
 	return "and" in query ? "and" : "or";
 }
-function isDisjunctiveQueryGroup(query) {
-	return "or" in query && query.or.length > 1;
-}
-/**
-* Whether a query tree nests an OCR leaf inside an OR group
-* @internal
-*/
-function hasOcrQueryInDisjunction(query, isInDisjunction = false) {
-	if (isQueryLeaf(query)) return query.target === "ocr" && isInDisjunction;
-	const isChildInDisjunction = isInDisjunction || isDisjunctiveQueryGroup(query);
-	for (const childQuery of getQueryGroupChildren(query)) if (hasOcrQueryInDisjunction(childQuery, isChildInDisjunction)) return true;
-	return false;
-}
 function getCompatibleIncludesGroupLeaves(query) {
 	if (!("or" in query) || query.or.length <= 1) return null;
 	const leafQueries = [];
@@ -896,21 +892,121 @@ function buildIncludesGroupQueryExpression(context, queries) {
 		bodyExpression: buildOrCtsQueryExpressionInternal(exactMemberHelpers.map((helper) => helper.callExpression))
 	}).callExpression, tokenizedQueryExpression]);
 }
-function buildQueryNode(context, query, isInDisjunction) {
+function buildCtsItemsPlan(queryExpression) {
+	return {
+		kind: "search",
+		itemPredicates: [],
+		queryExpressions: [queryExpression]
+	};
+}
+/**
+* Splice the children of same-kind child plans into their parent, so that a
+* nested group of the same operator does not cost an extra search
+*/
+function flattenItemsPlans(childPlans, kind) {
+	const flattenedPlans = [];
+	for (const childPlan of childPlans) {
+		if (childPlan.kind === kind) {
+			flattenedPlans.push(...childPlan.children);
+			continue;
+		}
+		flattenedPlans.push(childPlan);
+	}
+	return flattenedPlans;
+}
+/**
+* Fold the children of an `and` group into one plan
+*
+* Conjunction is the direction the item path predicates already run in, so
+* every child that is a plain search collapses into a single search, and only
+* the children that resolved to a union stay separate.
+*/
+function buildAndItemsPlan(childPlans) {
+	const mergedPlan = {
+		kind: "search",
+		itemPredicates: [],
+		queryExpressions: []
+	};
+	const unfoldablePlans = [];
+	for (const childPlan of flattenItemsPlans(childPlans, "intersect")) {
+		if (childPlan.kind !== "search") {
+			unfoldablePlans.push(childPlan);
+			continue;
+		}
+		for (const itemPredicate of childPlan.itemPredicates) if (!mergedPlan.itemPredicates.includes(itemPredicate)) mergedPlan.itemPredicates.push(itemPredicate);
+		mergedPlan.queryExpressions.push(...childPlan.queryExpressions);
+	}
+	if (unfoldablePlans.length === 0) return mergedPlan;
+	const intersectedPlans = mergedPlan.itemPredicates.length === 0 && mergedPlan.queryExpressions.length === 0 ? unfoldablePlans : [mergedPlan, ...unfoldablePlans];
+	return intersectedPlans.length === 1 ? intersectedPlans[0] ?? mergedPlan : {
+		kind: "intersect",
+		children: intersectedPlans
+	};
+}
+/**
+* Fold the children of an `or` group into one plan
+*
+* Item path predicates cannot be disjoined, so a child carrying one becomes its
+* own arm of a node union. Everything else is still a single CTS query.
+*/
+function buildOrItemsPlan(childPlans) {
+	const mergedQueryExpressions = [];
+	const unionedPlans = [];
+	for (const childPlan of flattenItemsPlans(childPlans, "union")) {
+		if (childPlan.kind === "search" && childPlan.itemPredicates.length === 0) {
+			mergedQueryExpressions.push(buildAndCtsQueryExpressionInternal(childPlan.queryExpressions));
+			continue;
+		}
+		unionedPlans.push(childPlan);
+	}
+	if (mergedQueryExpressions.length > 0) unionedPlans.unshift({
+		kind: "search",
+		itemPredicates: [],
+		queryExpressions: [buildOrCtsQueryExpressionInternal(mergedQueryExpressions)]
+	});
+	if (unionedPlans.length === 0) return buildCtsItemsPlan("cts:false-query()");
+	return unionedPlans.length === 1 ? unionedPlans[0] ?? buildCtsItemsPlan("cts:false-query()") : {
+		kind: "union",
+		children: unionedPlans
+	};
+}
+function buildItemsPlan(context, query) {
 	if (isQueryLeaf(query)) {
 		if (query.target === "ocr") {
-			if (isInDisjunction) throw new Error(OCR_DISJUNCTION_ERROR_MESSAGE, { cause: query });
-			registerOcrItemPredicate(context, query);
-			return "cts:true-query()";
+			const bindingName = registerOcrBinding(context, query);
+			return {
+				kind: "search",
+				itemPredicates: [query.isNegated === true ? `[not(@uuid = ${bindingName})]` : `[@uuid = ${bindingName}]`],
+				queryExpressions: []
+			};
 		}
 		const queryExpression = buildLeafQueryExpression(context, query);
-		return query.isNegated === true ? buildNotCtsQueryExpression(queryExpression) : queryExpression;
+		return buildCtsItemsPlan(query.isNegated === true ? buildNotCtsQueryExpression(queryExpression) : queryExpression);
 	}
 	const optimizedIncludesGroupQueries = getCompatibleIncludesGroupLeaves(query);
-	if (optimizedIncludesGroupQueries != null) return buildIncludesGroupQueryExpression(context, optimizedIncludesGroupQueries);
-	const isChildInDisjunction = isInDisjunction || isDisjunctiveQueryGroup(query);
-	const childQueryExpressions = Array.from(getQueryGroupChildren(query), (childQuery) => buildQueryNode(context, childQuery, isChildInDisjunction));
-	return (getQueryGroupOperator(query) === "and" ? buildAndCtsQueryExpressionInternal : buildOrCtsQueryExpressionInternal)(childQueryExpressions);
+	if (optimizedIncludesGroupQueries != null) return buildCtsItemsPlan(buildIncludesGroupQueryExpression(context, optimizedIncludesGroupQueries));
+	const childPlans = Array.from(getQueryGroupChildren(query), (childQuery) => buildItemsPlan(context, childQuery));
+	return getQueryGroupOperator(query) === "and" ? buildAndItemsPlan(childPlans) : buildOrItemsPlan(childPlans);
+}
+function collectItemsSearchPlans(plan, searchPlans) {
+	if (plan.kind === "search") {
+		searchPlans.push(plan);
+		return;
+	}
+	for (const childPlan of plan.children) collectItemsSearchPlans(childPlan, searchPlans);
+}
+function buildItemsPlanExpression(parameters) {
+	const { plan, baseItemsExpression, queryNamesByPlan } = parameters;
+	if (plan.kind === "search") {
+		const itemsExpression = `${baseItemsExpression}${plan.itemPredicates.join("")}`;
+		const queryName = queryNamesByPlan.get(plan);
+		return queryName == null ? itemsExpression : `cts:search(${itemsExpression}, ${queryName})`;
+	}
+	return `(${Array.from(plan.children, (childPlan) => buildItemsPlanExpression({
+		plan: childPlan,
+		baseItemsExpression,
+		queryNamesByPlan
+	})).join(plan.kind === "union" ? " | " : " intersect ")})`;
 }
 function buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids, belongsToCollectionPropertyVariableUuid) {
 	if (belongsToCollectionScopeUuids.length === 0) return null;
@@ -923,22 +1019,59 @@ function buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids,
 		}))))
 	});
 }
+/**
+* Compile a query tree into the XQuery `let` clauses that bind `$items` to the
+* matching Set items
+*
+* Most queries compile to a single `cts:search` over the Set item projections.
+* An `ocr` leaf cannot: the projections drop the `<ocr>` layer, so it resolves
+* to a search over the Resource documents whose matching UUIDs are joined back
+* in as an item path predicate. Path predicates only ever AND, so an `ocr` leaf
+* that sits under an `or` becomes its own arm of a node union instead, and one
+* that sits under an `and` alongside a union becomes an intersection.
+*
+* The searchable path has to stay inline in `cts:search`: binding it to a
+* variable first makes every query XDMP-UNSEARCHABLE.
+* @param parameters - The parameters for the compilation
+* @param parameters.queries - Recursive query tree to compile, if any
+* @param parameters.baseItemsExpression - The inline XQuery path selecting the items to search
+* @param parameters.scopeQueryExpression - An optional CTS query ANDed into every compiled search
+* @returns The prolog declaring the query helpers, and the `let` clauses binding `$items`
+*/
 function buildQueryPlan(parameters) {
-	const { queries } = parameters;
-	if (queries == null) return {
-		prolog: "",
-		queryExpression: null,
-		ocrBindings: [],
-		itemPredicates: ""
-	};
+	const { queries, baseItemsExpression, scopeQueryExpression } = parameters;
 	const context = createQueryCompilerContext();
-	const queryExpression = buildQueryNode(context, queries, false);
+	const plan = queries == null ? {
+		kind: "search",
+		itemPredicates: [],
+		queryExpressions: []
+	} : buildItemsPlan(context, queries);
+	const searchPlans = [];
+	collectItemsSearchPlans(plan, searchPlans);
+	const boundSearchPlans = [];
+	for (const searchPlan of searchPlans) {
+		const queryExpression = buildAndCtsQueryExpression([...searchPlan.queryExpressions, ...scopeQueryExpression == null ? [] : [scopeQueryExpression]]);
+		if (queryExpression != null) boundSearchPlans.push({
+			plan: searchPlan,
+			queryExpression
+		});
+	}
+	const queryNamesByPlan = /* @__PURE__ */ new Map();
+	const letClauses = Array.from(context.ocrBindings, (binding) => `let ${binding.name} := ${binding.expression}`);
+	for (const [index, boundSearchPlan] of boundSearchPlans.entries()) {
+		const queryName = boundSearchPlans.length === 1 ? "$query" : `$query${index + 1}`;
+		queryNamesByPlan.set(boundSearchPlan.plan, queryName);
+		letClauses.push(`let ${queryName} := ${boundSearchPlan.queryExpression}`);
+	}
+	letClauses.push(`let $items := ${buildItemsPlanExpression({
+		plan,
+		baseItemsExpression,
+		queryNamesByPlan
+	})}`);
 	return {
 		prolog: context.helperDeclarations.join("\n\n"),
-		queryExpression,
-		ocrBindings: context.ocrBindings,
-		itemPredicates: context.itemPredicates.join("")
+		itemsClause: letClauses.join("\n  ")
 	};
 }
 //#endregion
-export { OCR_DISJUNCTION_ERROR_MESSAGE, buildAndCtsQueryExpression, buildBelongsToCollectionQueryExpression, buildOcrTermQueryExpressions, buildQueryPlan, hasOcrQueryInDisjunction };
+export { buildBelongsToCollectionQueryExpression, buildQueryPlan };

package/dist/schemas.d.mts

@@ -38,7 +38,7 @@ declare const renderOptionsSchema: v.SchemaWithPipe<readonly [v.StringSchema<und
 declare const setPropertyValuesParametersSchema: v.ObjectSchema<{
   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">]>;
   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.SchemaWithPipe<readonly [v.GenericSchema<unknown, Query>, v.CheckAction<Query, "OCR queries cannot be nested inside an OR group because they are resolved by a document join instead of a CTS query">]>, undefined>, null>;
+  readonly queries: v.OptionalSchema<v.NullableSchema<v.GenericSchema<unknown, Query>, undefined>, null>;
   readonly attributes: v.OptionalSchema<v.ObjectSchema<{
     readonly bibliographies: v.GenericSchema<unknown, boolean>;
     readonly periods: v.GenericSchema<unknown, boolean>;
@@ -49,15 +49,14 @@ declare const setPropertyValuesParametersSchema: v.ObjectSchema<{
   readonly isLimitedToLeafPropertyValues: v.GenericSchema<unknown, boolean>;
 }, undefined>;
 /**
- * Schema for validating OCR matches parameters
+ * Schema for validating the parameters for the item OCR data fetching function
  * @internal
  */
-declare const ocrMatchesParametersSchema: v.ObjectSchema<{
-  readonly uuids: 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 UUID is required">]>;
-  readonly value: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "A search value is required">]>;
+declare const itemOcrDataParametersSchema: v.ObjectSchema<{
+  readonly uuid: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.CheckAction<string, "Invalid pseudo-UUID">]>;
+  readonly value: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.CheckAction<string, "A search value is required">]>;
   readonly matchMode: v.OptionalSchema<v.PicklistSchema<["includes", "exact"], undefined>, "includes">;
   readonly isCaseSensitive: v.GenericSchema<unknown, boolean>;
-  readonly maxMatchesPerItem: v.OptionalSchema<v.GenericSchema<unknown, number>, 50>;
 }, undefined>;
 /**
  * Schema for validating Set items parameters
@@ -66,7 +65,7 @@ declare const ocrMatchesParametersSchema: v.ObjectSchema<{
 declare const setItemsParametersSchema: v.ObjectSchema<{
   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">]>;
   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.SchemaWithPipe<readonly [v.GenericSchema<unknown, Query>, v.CheckAction<Query, "OCR queries cannot be nested inside an OR group because they are resolved by a document join instead of a CTS query">]>, undefined>, null>;
+  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<{
@@ -86,4 +85,4 @@ declare const setItemsParametersSchema: v.ObjectSchema<{
   readonly pageSize: v.OptionalSchema<v.GenericSchema<unknown, number>, 48>;
 }, undefined>;
 //#endregion
-export { componentSchema, gallerySchema, iso639_3Schema, ocrMatchesParametersSchema, renderOptionsSchema, setItemsParametersSchema, setPropertyValuesParametersSchema, uuidSchema };
+export { componentSchema, gallerySchema, iso639_3Schema, itemOcrDataParametersSchema, renderOptionsSchema, setItemsParametersSchema, setPropertyValuesParametersSchema, uuidSchema };

package/dist/schemas.mjs

@@ -1,6 +1,5 @@
 import { isPseudoUuid } from "./utilities.mjs";
 import "./helpers.mjs";
-import { OCR_DISJUNCTION_ERROR_MESSAGE, hasOcrQueryInDisjunction } from "./query.mjs";
 import * as v from "valibot";
 //#region src/schemas.ts
 const positiveNumber = (message) => v.pipe(v.number(), v.minValue(1, message));
@@ -175,7 +174,7 @@ const setQuerySchema = v.lazy(() => v.union([
 * Schema for validating Set queries
 * @internal
 */
-const setQueriesSchema = v.optional(v.nullable(v.pipe(setQuerySchema, v.check((query) => !hasOcrQueryInDisjunction(query), OCR_DISJUNCTION_ERROR_MESSAGE))), null);
+const setQueriesSchema = v.optional(v.nullable(setQuerySchema), null);
 /**
 * Schema for validating Set items sort
 * @internal
@@ -222,15 +221,14 @@ const setPropertyValuesParametersSchema = v.object({
 	isLimitedToLeafPropertyValues: defaultBoolean(false)
 });
 /**
-* Schema for validating OCR matches parameters
+* Schema for validating the parameters for the item OCR data fetching function
 * @internal
 */
-const ocrMatchesParametersSchema = v.object({
-	uuids: v.pipe(v.array(uuidSchema), v.minLength(1, "At least one UUID is required")),
-	value: v.pipe(v.string(), v.minLength(1, "A search value is required")),
+const itemOcrDataParametersSchema = v.object({
+	uuid: uuidSchema,
+	value: v.pipe(v.string(), v.check((value) => value.trim() !== "", "A search value is required")),
 	matchMode: v.optional(v.picklist(["includes", "exact"]), "includes"),
-	isCaseSensitive: defaultBoolean(false),
-	maxMatchesPerItem: v.optional(positiveNumber("Max matches per item must be positive"), 50)
+	isCaseSensitive: defaultBoolean(false)
 });
 /**
 * Schema for validating Set items parameters
@@ -245,4 +243,4 @@ const setItemsParametersSchema = v.object({
 	pageSize: v.optional(positiveNumber("Page size must be positive"), 48)
 });
 //#endregion
-export { componentSchema, gallerySchema, iso639_3Schema, ocrMatchesParametersSchema, renderOptionsSchema, setItemsParametersSchema, setPropertyValuesParametersSchema, uuidSchema };
+export { componentSchema, gallerySchema, iso639_3Schema, itemOcrDataParametersSchema, renderOptionsSchema, setItemsParametersSchema, setPropertyValuesParametersSchema, uuidSchema };

package/dist/types/index.d.mts

@@ -263,58 +263,29 @@ type ImageMap = {
   height: number;
 };
 /**
- *  Vertex of an OCR word's bounding polygon in OCHRE
- */
-type OcrPoint = {
-  x: number;
-  y: number;
-};
-/**
- *  Word recognized within an OCR text line in OCHRE
- */
-type OcrWord = {
-  content: string;
-  x: number;
-  y: number;
-  width: number;
-  height: number;
-  vertices: Array<OcrPoint>;
-};
-/**
- *  Text line of an OCR text block in OCHRE
- */
-type OcrTextLine = {
-  content: string;
-  words: Array<OcrWord>;
-};
-/**
- *  Text block of an OCR page in OCHRE
- */
-type OcrTextBlock = {
-  lines: Array<OcrTextLine>;
-};
-/**
- *  OCR page of a resource in OCHRE
- */
-type OcrPage = {
-  number: number | null;
-  fileName: string | null;
-  width: number | null;
-  height: number | null;
-  blocks: Array<OcrTextBlock>;
-};
-/**
- *  A run of adjacent OCR words matching a search value in OCHRE
+ *  Positioned OCR string in OCHRE
+ *
+ *  OCHRE gives no guarantee about the node hierarchy inside a Resource's
+ *  `<ocr>` layer, so only `<string>` nodes are parsed, at whatever depth they
+ *  occur. `x` and `y` come from `HPOS` and `VPOS` and locate the top-left
+ *  corner of the string's box, while `vertices` is its full bounding polygon,
+ *  which is not necessarily rectangular. Every geometry attribute is optional
+ *  in the source, so each one is null when absent or unparseable.
  *
- *  `uuid` is the requested resource, while `resourceUuid` is the resource that
- *  owns the OCR page — they differ when the OCR lives on a child page resource.
+ *  `resourceUuid` is the Resource that owns the OCR layer, which differs from
+ *  the requested item when the OCR lives on a child Resource.
  */
-type OcrMatch = {
-  uuid: string;
+type OcrString = {
   resourceUuid: string | null;
-  page: Omit<OcrPage, "blocks">;
   content: string;
-  words: Array<OcrWord>;
+  x: number | null;
+  y: number | null;
+  width: number | null;
+  height: number | null;
+  vertices: Array<{
+    x: number;
+    y: number;
+  }>;
 };
 /**
  *  Note in OCHRE
@@ -734,7 +705,6 @@ type Resource<T extends LanguageCodes = LanguageCodes, U extends ItemPayloadKind
   image: Image<T> | null;
   document: MultilingualString<T> | null;
   imageMap: ImageMap | null;
-  ocr: Array<OcrPage>;
   coordinates: Array<Coordinates<T>>;
   periods: Array<Period<T, "embedded">>;
   links: ItemLinks<T>;
@@ -845,12 +815,13 @@ type SetItemsSort = {
 /**
  * Represents a leaf query for Set items
  *
- * The `ocr` target matches the OCR text layer of resources. Because OCR is not
- * carried by Set item projections, it is resolved by a document join rather
- * than a CTS term, which means `ocr` leaves compose with `and` and `isNegated`
- * but cannot be nested inside an `or` group. Both match modes are adjacency
- * based: `includes` allows stemming and wildcards, `exact` requires whole OCR
- * words. OCR carries no language, so `ocr` leaves take no `language`.
+ * The `ocr` target matches the OCR text layer of Resource items. Set item
+ * projections do not carry `<ocr>`, so it is resolved by a document join rather
+ * than by a CTS term, and it composes with `and`, `or`, and `isNegated` at the
+ * cost of one extra search per distinct OCR value. Each `<string>` in that
+ * 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`.
  */
 type QueryLeaf = {
   target: "property";
@@ -944,4 +915,4 @@ type QueryGroup = {
  */
 type Query = QueryLeaf | QueryGroup;
 //#endregion
-export { 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, OcrMatch, OcrPage, OcrPoint, OcrTextBlock, OcrTextLine, OcrWord, Period, PeriodItemLink, Person, PersonItemLink, Prettify, 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 };
+export { 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, Prettify, 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 };

package/dist/utilities.d.mts

@@ -20,6 +20,30 @@ declare function isPseudoUuid(value: string): boolean;
  * @returns The escaped string literal
  */
 declare function stringLiteral(value: string): string;
+/**
+ * XQuery prolog declaring `local:omit-supplemental`, which drops every element
+ * carrying `supplemental="true"` from a node sequence, at any depth.
+ *
+ * Subtrees without a supplemental descendant are returned by reference, so
+ * nodes are only copied along the path leading to an omitted element. The
+ * lookahead walks the attribute axis (`//@supplemental`) rather than testing
+ * every element, which measures around three times faster on large documents.
+ *
+ * Must be declared before any query body that calls {@link omitSupplemental}.
+ */
+declare const SUPPLEMENTAL_XQUERY_PROLOG = "declare function local:omit-supplemental($nodes as node()*) as node()* {\n  for $node in $nodes\n  return\n    if ($node instance of element())\n    then\n      if ($node/@supplemental = \"true\")\n      then ()\n      else if (empty($node//@supplemental[. = \"true\"]))\n      then $node\n      else element { node-name($node) } {\n        $node/@*,\n        local:omit-supplemental($node/node())\n      }\n    else $node\n};";
+/**
+ * Wrap an XQuery node expression so supplemental nodes are omitted from it
+ * @param expression - The XQuery expression returning the nodes to filter
+ * @returns The wrapped XQuery expression
+ */
+declare function omitSupplemental(expression: string): string;
+/**
+ * XQuery predicate keeping only nodes that are neither supplemental themselves
+ * nor nested inside a supplemental node. Use it when aggregating over nodes
+ * instead of returning them.
+ */
+declare const NOT_SUPPLEMENTAL_PREDICATE = "[not(ancestor-or-self::*[@supplemental = \"true\"])]";
 /**
  * Flatten a properties array
  * @param properties - The properties to flatten
@@ -28,4 +52,4 @@ declare function stringLiteral(value: string): string;
  */
 declare function flattenProperties<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<Property<T> | SetItemProperty<T>>): Array<SetItemProperty<T>>;
 //#endregion
-export { createSchemaValidationError, flattenProperties, getErrorOutput, isPseudoUuid, stringLiteral };
+export { NOT_SUPPLEMENTAL_PREDICATE, SUPPLEMENTAL_XQUERY_PROLOG, createSchemaValidationError, flattenProperties, getErrorOutput, isPseudoUuid, omitSupplemental, stringLiteral };