ochre-sdk 1.0.13 → 1.0.14

package/dist/parsers/string.mjs

@@ -0,0 +1,477 @@
+import { TEXT_ANNOTATION_UUID } from "../constants.mjs";
+import { serializeMDXText } from "./mdx.mjs";
+import { MultilingualString } from "./multilingual.mjs";
+import { renderOptionsSchema, whitespaceSchema } from "../schemas.mjs";
+import { getXMLSourceIndex } from "../xml/metadata.mjs";
+import * as v from "valibot";
+//#region src/parsers/string.ts
+const TEXT_ANNOTATION_TOKEN = "text-annotation";
+const TEXT_STYLING_TOKEN = "text-styling";
+const HOVER_CARD_TOKEN = "hover-card";
+const ITEM_PAGE_TOKEN = "item-page";
+const ENTRY_PAGE_TOKEN = "entry-page";
+const VARIANT_TOKEN = "variant";
+const HEADING_LEVEL_TOKEN = "heading-level";
+const MDX_QUOTED_ATTRIBUTE_ESCAPE_REGEX = /[\n\r"]/;
+const MDX_RENDER_ELEMENTS = {
+	bold: "strong",
+	italic: "em",
+	underline: "u"
+};
+function isXMLRichTextLink(value) {
+	return typeof value === "object" && value != null;
+}
+function getLinkStringProperty(link, property) {
+	switch (property) {
+		case "uuid": return "uuid" in link && typeof link.uuid === "string" ? link.uuid : null;
+		case "href": return "href" in link && typeof link.href === "string" ? link.href : null;
+		case "height": return "height" in link && link.height != null ? link.height.toString() : null;
+		case "width": return "width" in link && link.width != null ? link.width.toString() : null;
+	}
+}
+function transformPermanentIdentificationUrl(url) {
+	return url.replace("https://pi.lib.uchicago.edu/1001/org/ochre/", "https://ochre.lib.uchicago.edu/ochre/v2/ochre.php?uuid=");
+}
+/**
+* Applies text rendering options (bold, italic, underline) to a string
+*
+* @param contentString - The string content to render
+* @param renderString - Space-separated string of render options
+* @param rendering - Which text rendering to produce
+* @returns String with rich-text formatting applied
+* @internal
+*/
+function parseRenderOptions(contentString, renderString, rendering) {
+	const { success, output } = v.safeParse(renderOptionsSchema, renderString);
+	if (!success) return contentString;
+	if (rendering !== "rich") return contentString.replaceAll("'", "'");
+	return applyRichRenderOptions(contentString, output).replaceAll("'", "'");
+}
+function applyRichRenderOptions(contentString, options) {
+	const withoutLeadingWhitespace = contentString.trimStart();
+	const leadingWhitespace = contentString.slice(0, contentString.length - withoutLeadingWhitespace.length);
+	const renderableContent = withoutLeadingWhitespace.trimEnd();
+	const trailingWhitespace = withoutLeadingWhitespace.slice(renderableContent.length);
+	if (renderableContent === "") return contentString;
+	return `${leadingWhitespace}${applyMDXRenderElements(renderableContent, options)}${trailingWhitespace}`;
+}
+function applyMDXRenderElements(contentString, options) {
+	let result = contentString;
+	for (const option of options) {
+		const element = MDX_RENDER_ELEMENTS[option];
+		result = `<${element}>${result}</${element}>`;
+	}
+	return result;
+}
+/**
+* Applies whitespace options to a string (newline)
+*
+* @param contentString - The string content to modify
+* @param whitespace - Space-separated string of whitespace options
+* @param rendering - Which text rendering to produce
+* @returns String with whitespace modifications applied
+*
+* @internal
+*/
+function parseWhitespace(contentString, whitespace, rendering) {
+	let returnString = contentString;
+	const { success, output } = v.safeParse(whitespaceSchema, whitespace);
+	if (!success) return contentString;
+	for (const option of output) switch (option) {
+		case "newline":
+			if (rendering === "rich") returnString = returnString.trim() === "***" ? `${returnString}\n` : `<br />\n${returnString}`;
+			else returnString = `\n${returnString}`;
+			break;
+		case "trailing":
+			returnString = `${returnString} `;
+			break;
+		case "leading":
+			returnString = ` ${returnString}`;
+			break;
+	}
+	return returnString.replaceAll("&#39;", "'");
+}
+/**
+* Parses XML string into a formatted string with whitespace and rendering options
+*
+* @param string - XML string to parse
+* @param options - Options for parsing
+* @param options.rendering - Which text rendering to produce
+* @returns Formatted string with whitespace and rendering options
+*
+* @internal
+*/
+function parseXMLStringVariant(string, options) {
+	let returnString = parseXMLStringPayload(string, options);
+	if (string.rend != null) returnString = parseRenderOptions(returnString, string.rend, options.rendering);
+	if (string.whitespace != null) returnString = parseWhitespace(returnString, string.whitespace, options.rendering);
+	return returnString;
+}
+function parseXMLStringPayload(string, options) {
+	const payload = string.payload ?? "";
+	return options.rendering === "rich" ? serializeMDXText(payload) : payload;
+}
+function parseXMLString(string) {
+	return {
+		text: parseXMLStringVariant(string, { rendering: "plain" }),
+		richText: parseXMLStringVariant(string, { rendering: "rich" })
+	};
+}
+/**
+* Creates an MDX component based on the variant
+*
+* @param variant - The variant of the component
+* @param properties - The properties of the component
+* @param properties.uuid - The UUID of the component
+* @param properties.href - The href of the component
+* @param properties.height - The height of the component
+* @param properties.width - The width of the component
+* @param properties.content - The content of the component
+* @param properties.text - The text of the component
+* @returns The MDX component as a string
+*
+* @internal
+*/
+function createMDXComponent(variant, properties) {
+	const { uuid, href, height, width, content, text } = properties;
+	const tooltipContent = getDistinctTooltipContent(content, text);
+	let returnString = "";
+	switch (variant) {
+		case "inlineImage":
+			returnString = `<InlineImage${createMDXStringAttribute("uuid", uuid ?? "null")}${createMDXStringAttribute("content", content)} height={${height ?? "null"}} width={${width ?? "null"}} />`;
+			break;
+		case "internalLink":
+			returnString = `<InternalLink${createMDXStringAttribute("uuid", uuid ?? "null")}${createMDXStringAttribute("content", tooltipContent)}>${text}</InternalLink>`;
+			break;
+		case "externalLink":
+			returnString = `<ExternalLink${createMDXStringAttribute("href", href == null ? "#" : transformPermanentIdentificationUrl(href))}${createMDXStringAttribute("content", tooltipContent)}>${text}</ExternalLink>`;
+			break;
+		case "documentLink":
+			returnString = `<ExternalLink${createMDXStringAttribute("href", `https://ochre.lib.uchicago.edu/ochre/v2/ochre.php?uuid=${uuid}&load`)}${createMDXStringAttribute("content", tooltipContent)}>${text}</ExternalLink>`;
+			break;
+		case "tooltipSpan":
+			returnString = `<TooltipSpan${createMDXStringAttribute("content", content)}>${text}</TooltipSpan>`;
+			break;
+	}
+	return returnString;
+}
+function getDistinctTooltipContent(content, textContent) {
+	return content === textContent ? void 0 : content;
+}
+function createMDXStringAttribute(name, value) {
+	if (value == null || value === "") return "";
+	return ` ${name}=${MDX_QUOTED_ATTRIBUTE_ESCAPE_REGEX.test(value) ? `{${JSON.stringify(value)}}` : `"${value}"`}`;
+}
+function applyWhitespaceToResult(result, whitespace, rendering) {
+	return whitespace == null ? result : parseWhitespace(result, whitespace, rendering);
+}
+function getPropertyValueUuid(property) {
+	const value = property?.value?.[0];
+	return value?.uuid == null || value.uuid === "" ? null : value.uuid;
+}
+function getFirstPropertyMetadata(item) {
+	const itemProperty = item.properties?.property[0];
+	if (itemProperty == null) return null;
+	return {
+		labelUuid: itemProperty.label.uuid,
+		valueUuid: getPropertyValueUuid(itemProperty)
+	};
+}
+function parseContentLikeForLanguage(value, options) {
+	if (value == null) return "";
+	if (!("content" in value)) return parseXMLString(value).text;
+	const contentItem = value.content.find((item) => item.lang === options.language) ?? value.content[0];
+	if (contentItem == null) return "";
+	const languages = [contentItem.lang];
+	return parseXMLContent({ content: [contentItem] }, { languages }).getText(contentItem.lang);
+}
+function parsePropertyValueText(property, options) {
+	const value = property?.value?.[0];
+	if (value == null) return "";
+	if (value.rawValue != null) return value.rawValue;
+	if (value.payload != null) return value.payload;
+	if (value.slug != null) return value.slug;
+	if (value.content != null) return parseContentLikeForLanguage(value, options);
+	return "";
+}
+function normalizePropertyToken(value) {
+	return value.trim().toLowerCase().replaceAll(/[\s_]+/g, "-");
+}
+function propertyLabelMatches(property, uuid, tokens, options) {
+	if (uuid !== "" && property.label.uuid === uuid) return true;
+	const label = normalizePropertyToken(parseContentLikeForLanguage(property.label, options));
+	return tokens.includes(label);
+}
+function propertyValueMatches(property, uuid, tokens, options) {
+	if (uuid !== "" && getPropertyValueUuid(property) === uuid) return true;
+	const value = normalizePropertyToken(parsePropertyValueText(property, options));
+	return tokens.includes(value);
+}
+function extractAnnotationMetadata(item, options) {
+	const result = {
+		linkVariant: null,
+		textStyling: null
+	};
+	const itemProperty = item.properties?.property[0];
+	if (itemProperty == null) return result;
+	if (!propertyLabelMatches(itemProperty, "f1c131b6-1498-48a4-95bf-a9edae9fd518", ["presentation"], options) || !propertyValueMatches(itemProperty, "b9ca2732-78f4-416e-b77f-dae7647e68a9", [TEXT_ANNOTATION_TOKEN], options)) return result;
+	for (const textAnnotationProperty of itemProperty.property ?? []) {
+		if (propertyValueMatches(textAnnotationProperty, "c7f6a08a-f07b-49b6-bcb1-af485da3c58f", [HOVER_CARD_TOKEN], options)) {
+			result.linkVariant = "hover-card";
+			continue;
+		}
+		if (propertyValueMatches(textAnnotationProperty, "bf4476ab-6bc8-40d0-a001-1446213c72ce", [ITEM_PAGE_TOKEN], options)) {
+			result.linkVariant = "item-page";
+			continue;
+		}
+		if (propertyValueMatches(textAnnotationProperty, "9d52db95-a9cf-45f7-a0bf-fc9ba9f0aae0", [ENTRY_PAGE_TOKEN], options)) {
+			result.linkVariant = "entry-page";
+			continue;
+		}
+		if (propertyValueMatches(textAnnotationProperty, "3e6f86ab-df81-45ae-8257-e2867357df56", [TEXT_STYLING_TOKEN], options)) {
+			let variant = "block";
+			let size = "md";
+			let headingLevel = null;
+			const cssStyles = [];
+			const textStylingProperties = textAnnotationProperty.property ?? [];
+			for (const textStylingProperty of textStylingProperties) {
+				if (propertyLabelMatches(textStylingProperty, "e1647bef-d801-4100-bdde-d081c422f763", [VARIANT_TOKEN], options)) {
+					variant = parsePropertyValueText(textStylingProperty, options);
+					for (const nestedProperty of textStylingProperty.property ?? []) if (propertyLabelMatches(nestedProperty, "", ["size"], options)) size = parsePropertyValueText(nestedProperty, options);
+					continue;
+				}
+				if (propertyLabelMatches(textStylingProperty, "d4266f0b-3f8d-4b32-8c15-4b229c8bb11e", [HEADING_LEVEL_TOKEN], options)) {
+					headingLevel = parsePropertyValueText(textStylingProperty, options);
+					continue;
+				}
+				cssStyles.push({
+					label: parseContentLikeForLanguage(textStylingProperty.label, options),
+					value: parsePropertyValueText(textStylingProperty, options)
+				});
+			}
+			result.textStyling = {
+				variant,
+				size,
+				headingLevel,
+				cssStyles
+			};
+			continue;
+		}
+	}
+	return result;
+}
+function hasRichTextEnvelope(item) {
+	return item.properties?.property[0] != null || getXMLRichTextLinks(item).length > 0;
+}
+function parseXMLStringItem(item, contentItem, options) {
+	if (!(item.payload != null || item.string != null) && getXMLRichTextLinks(item).length === 0) return item.whitespace == null ? "" : parseWhitespace("", item.whitespace, options.rendering);
+	if (hasRichTextEnvelope(item)) {
+		let linkString = item.payload != null ? parseXMLStringPayload(item, { rendering: options.rendering }) : parseNestedStringItems(item.string ?? [], contentItem, { ...options });
+		if (item.rend != null) linkString = parseRenderOptions(linkString, item.rend, options.rendering);
+		if (options.rendering === "plain") return applyWhitespaceToResult(linkString, item.whitespace, options.rendering);
+		return renderRichTextItem(item, linkString, contentItem, options);
+	}
+	if (item.payload != null) return parseXMLStringVariant(item, { rendering: options.rendering });
+	let result = parseNestedStringItems(item.string ?? [], contentItem, options);
+	if (item.rend != null) result = parseRenderOptions(result, item.rend, options.rendering);
+	return applyWhitespaceToResult(result, item.whitespace, options.rendering);
+}
+function parseNestedStringItems(items, contentItem, options) {
+	let result = "";
+	for (const item of items) result += parseXMLStringItem(item, contentItem, options);
+	return result;
+}
+function isTextAnnotationMarkerLink(link) {
+	return getLinkStringProperty(link, "uuid") === TEXT_ANNOTATION_UUID;
+}
+function wrapWithTextStyling(content, textStyling) {
+	if (textStyling == null) return content;
+	return `<Annotation type="text-styling"${createMDXStringAttribute("variant", textStyling.variant)}${createMDXStringAttribute("size", textStyling.size)}${createMDXStringAttribute("headingLevel", textStyling.headingLevel ?? void 0)}${textStyling.cssStyles.length > 0 ? ` cssStyles={{default: ${JSON.stringify(textStyling.cssStyles)}, tablet: [], mobile: []}}` : ""}>${content}</Annotation>`;
+}
+function createInternalLinkComponent(properties) {
+	const innerContent = wrapWithTextStyling(properties.text, properties.annotationMetadata.textStyling);
+	switch (properties.annotationMetadata.linkVariant) {
+		case "hover-card": return `<Annotation type="hover-card"${createMDXStringAttribute("uuid", properties.uuid ?? "null")}>${innerContent}</Annotation>`;
+		case "item-page": return `<InternalLink type="item"${createMDXStringAttribute("uuid", properties.uuid ?? "null")}>${innerContent}</InternalLink>`;
+		case "entry-page": return `<InternalLink type="entry"${createMDXStringAttribute("uuid", properties.uuid ?? "null")}>${innerContent}</InternalLink>`;
+		default: return `<InternalLink${createMDXStringAttribute("uuid", properties.uuid ?? "null")}${properties.propertyMetadata != null ? `${createMDXStringAttribute("properties", properties.propertyMetadata.labelUuid)}${createMDXStringAttribute("value", properties.propertyMetadata.valueUuid ?? void 0)}` : ""}${createMDXStringAttribute("content", getDistinctTooltipContent(properties.content, properties.text))}>${innerContent}</InternalLink>`;
+	}
+}
+function getXMLRichTextLinks(item) {
+	const links = [];
+	let fallbackIndex = 0;
+	for (const rawLinks of Object.values(item.links ?? {})) {
+		if (!Array.isArray(rawLinks)) continue;
+		for (const rawLink of rawLinks) if (isXMLRichTextLink(rawLink) && !isTextAnnotationMarkerLink(rawLink)) {
+			links.push({
+				link: rawLink,
+				fallbackIndex
+			});
+			fallbackIndex += 1;
+		}
+	}
+	links.sort((left, right) => {
+		const leftIndex = getXMLSourceIndex(left.link);
+		const rightIndex = getXMLSourceIndex(right.link);
+		if (leftIndex != null && rightIndex != null && leftIndex !== rightIndex) return leftIndex - rightIndex;
+		return left.fallbackIndex - right.fallbackIndex;
+	});
+	const sortedLinks = [];
+	for (const { link } of links) sortedLinks.push(link);
+	return sortedLinks;
+}
+function renderRichTextItem(item, linkString, contentItem, options) {
+	const { languages, rendering } = options;
+	const annotationMetadata = extractAnnotationMetadata(item, { language: contentItem.lang });
+	const links = getXMLRichTextLinks(item);
+	if (links.length === 0) return applyWhitespaceToResult(wrapWithTextStyling(linkString, annotationMetadata.textStyling), item.whitespace, rendering);
+	let result = "";
+	for (const link of links) {
+		const linkContent = link.identification != null ? "content" in link.identification.label ? parseXMLContent(link.identification.label, { languages }) : MultilingualString.create(contentItem.lang, parseXMLString(link.identification.label), languages) : MultilingualString.create(contentItem.lang, "", languages);
+		const contentText = (rendering === "rich" ? linkContent.getExactRichText(contentItem.lang) : linkContent.getExactText(contentItem.lang)) ?? "";
+		if ("type" in link && link.type != null) switch (link.type) {
+			case "IIIF":
+			case "image":
+				if ("rend" in link && link.rend === "inline") {
+					const component = createMDXComponent("inlineImage", {
+						uuid: getLinkStringProperty(link, "uuid"),
+						href: getLinkStringProperty(link, "href") ?? void 0,
+						height: getLinkStringProperty(link, "height") ?? void 0,
+						width: getLinkStringProperty(link, "width") ?? void 0,
+						content: contentText,
+						text: linkString
+					});
+					result += applyWhitespaceToResult(component, item.whitespace, rendering);
+				} else if (link.publicationDateTime != null) {
+					const component = createInternalLinkComponent({
+						uuid: getLinkStringProperty(link, "uuid"),
+						text: linkString,
+						content: contentText,
+						annotationMetadata
+					});
+					result += applyWhitespaceToResult(component, item.whitespace, rendering);
+				} else {
+					const component = createMDXComponent("tooltipSpan", {
+						uuid: getLinkStringProperty(link, "uuid"),
+						text: linkString,
+						content: contentText
+					});
+					result += applyWhitespaceToResult(component, item.whitespace, rendering);
+				}
+				break;
+			case "internalDocument": {
+				const component = createInternalLinkComponent({
+					uuid: getLinkStringProperty(link, "uuid"),
+					text: linkString,
+					content: contentText,
+					annotationMetadata,
+					propertyMetadata: getFirstPropertyMetadata(item)
+				});
+				result += applyWhitespaceToResult(component, item.whitespace, rendering);
+				break;
+			}
+			case "externalDocument": {
+				const component = link.publicationDateTime != null ? createMDXComponent("documentLink", {
+					uuid: getLinkStringProperty(link, "uuid"),
+					text: linkString,
+					content: contentText
+				}) : createMDXComponent("tooltipSpan", {
+					uuid: getLinkStringProperty(link, "uuid"),
+					text: linkString,
+					content: contentText
+				});
+				result += applyWhitespaceToResult(component, item.whitespace, rendering);
+				break;
+			}
+			case "webpage": {
+				const component = createMDXComponent("externalLink", {
+					uuid: getLinkStringProperty(link, "uuid"),
+					href: getLinkStringProperty(link, "href") ?? "#",
+					text: linkString,
+					content: contentText
+				});
+				result += applyWhitespaceToResult(component, item.whitespace, rendering);
+				break;
+			}
+		}
+		else if (link.publicationDateTime != null) {
+			const component = createInternalLinkComponent({
+				uuid: getLinkStringProperty(link, "uuid"),
+				text: linkString,
+				content: contentText,
+				annotationMetadata
+			});
+			result += applyWhitespaceToResult(component, item.whitespace, rendering);
+		} else {
+			const component = createMDXComponent("tooltipSpan", {
+				uuid: getLinkStringProperty(link, "uuid"),
+				text: linkString,
+				content: contentText
+			});
+			result += applyWhitespaceToResult(component, item.whitespace, rendering);
+		}
+	}
+	return result;
+}
+/**
+* Parses rich text content into a formatted string with links and annotations
+*
+* @param item - XML-based rich text item to parse
+* @param options - Options for parsing
+* @param options.languages - Languages of the content
+* @returns Plain and rich formatted strings
+*
+* @internal
+*/
+function parseXMLContent(item, options) {
+	const { languages } = options;
+	const aliases = extractAliases(item) ?? [];
+	const content = {};
+	for (const contentItem of item.content) {
+		if (contentItem.lang === "zxx" || !languages.includes(contentItem.lang)) continue;
+		const language = contentItem.lang;
+		const entries = content[language] ?? [];
+		entries.push(parseXMLContentItem(contentItem, { languages }));
+		content[language] = entries;
+	}
+	if (Object.keys(content).length > 0) return MultilingualString.fromEntries(content, languages, { aliases });
+	for (const contentItem of item.content) {
+		if (contentItem.lang === "zxx") continue;
+		const fallbackText = parseXMLContentItem(contentItem, { languages: [contentItem.lang] });
+		const fallbackContent = {};
+		for (const language of languages) fallbackContent[language] = [fallbackText];
+		return MultilingualString.fromEntries(fallbackContent, languages, { aliases });
+	}
+	return MultilingualString.empty(languages, { aliases });
+}
+function parseXMLContentItem(contentItem, options) {
+	return {
+		text: parseNestedStringItems(contentItem.string, contentItem, {
+			...options,
+			rendering: "plain"
+		}),
+		richText: parseNestedStringItems(contentItem.string, contentItem, {
+			...options,
+			rendering: "rich"
+		})
+	};
+}
+/**
+* Extracts alias strings from XMLContent where lang="zxx"
+* @param content - The XMLContent to extract aliases from
+* @returns Array of alias strings, or null if none found
+*
+* @internal
+*/
+function extractAliases(content) {
+	if (content == null) return null;
+	const aliases = [];
+	for (const contentItem of content.content) {
+		if (contentItem.lang !== "zxx") continue;
+		const alias = parseXMLContentItem(contentItem, { languages: ["zxx"] }).text;
+		if (alias !== "") aliases.push(alias);
+	}
+	return aliases.length > 0 ? aliases : null;
+}
+//#endregion
+export { extractAliases, parseXMLContent, parseXMLString, transformPermanentIdentificationUrl };

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

@@ -0,0 +1,20 @@
+import { Webpage, Website } from "../../types/website.mjs";
+import { XMLWebsiteData, XMLWebsiteResource } from "../../xml/types.mjs";
+import { ParserOptions } from "../helpers.mjs";
+
+//#region src/parsers/website/index.d.ts
+/**
+ * Parses raw bounds data into a standardized bounds structure
+ *
+ * @param bounds - Raw bounds data in OCHRE format
+ * @returns Parsed bounds object
+ */
+declare function parseBounds(bounds: string): [[number, number], [number, number]];
+declare function parseWebpageView<T extends ReadonlyArray<string>>(view: {
+  resource?: Array<XMLWebsiteResource>;
+} | undefined, options: ParserOptions<T>, context: Pick<Website<T>, "belongsTo" | "metadata">): Webpage<T> | null;
+declare function parseWebsite<const T extends ReadonlyArray<string> = ReadonlyArray<string>>(data: XMLWebsiteData, options?: {
+  languages?: T;
+}): Website<T>;
+//#endregion
+export { parseBounds, parseWebpageView, parseWebsite };