ochre-sdk 1.0.78 → 1.1.0

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

@@ -0,0 +1,64 @@
+//#region src/parsers/website/slug.d.ts
+/**
+ * How a website page slug is built
+ *
+ * The rule runs in two places: here, while parsing a website, and inside the
+ * website metadata fetcher's XQuery, which resolves a slug to a page without
+ * shipping the whole tree. Both adapters live in this module so the rule
+ * cannot drift. The only difference between them is how "no prefix" is
+ * spelled: `undefined` in TypeScript, the empty string in XQuery, which has no
+ * way to pass an absent argument.
+ */
+/**
+ * The prefix OCHRE puts on a segment page's slug to keep it unique
+ */
+export declare const SEGMENT_UNIQUE_SLUG_PREFIX_PATTERN: string;
+/**
+ * The separator between a slug and its prefix
+ */
+export declare const WEBSITE_PAGE_SLUG_SEPARATOR = "/";
+/**
+ * The full slug of every page in a website, keyed by the page's UUID
+ *
+ * Resolved before parsing begins, because a link on any page can point at any
+ * other page and the target's slug depends on where that target sits in the
+ * tree.
+ * @internal
+ */
+export type WebsitePageSlugs = ReadonlyMap<string, string>;
+/**
+ * Strip the uniqueness prefix from a website page slug
+ * @param slug - The raw slug
+ * @returns The cleaned slug, or null when there was none
+ * @internal
+ */
+export declare function cleanWebsitePageSlug(slug: string | undefined): string | null;
+/**
+ * Join a website page slug onto the slug of the segment holding it
+ * @param slug - The page slug
+ * @param slugPrefix - The slug of the enclosing segment, if any
+ * @returns The full slug
+ * @internal
+ */
+export declare function prefixSlug(slug: string, slugPrefix: string | undefined): string;
+/**
+ * The slug a page gives its own child pages
+ *
+ * A page only prefixes its children once it is itself inside a segment, so a
+ * top-level website keeps flat page slugs.
+ * @param pageSlug - The page's own full slug
+ * @param slugPrefix - The prefix the page was resolved with
+ * @returns The prefix for the page's children, or undefined for no prefix
+ * @internal
+ */
+export declare function childSlugPrefix(pageSlug: string, slugPrefix: string | undefined): string | undefined;
+/**
+ * The XQuery counterpart of {@link cleanWebsitePageSlug},
+ * {@link prefixSlug} and {@link childSlugPrefix}
+ *
+ * Declares `local:clean-slug`, `local:page-slug` and
+ * `local:page-child-slug-prefix`. "No prefix" is the empty string here.
+ * @internal
+ */
+export declare const WEBSITE_PAGE_SLUG_DECLARATIONS: string;
+//#endregion

package/dist/parsers/website/slug.mjs

@@ -0,0 +1,82 @@
+import { stringLiteral } from "../../xquery.mjs";
+//#region src/parsers/website/slug.ts
+/**
+* How a website page slug is built
+*
+* The rule runs in two places: here, while parsing a website, and inside the
+* website metadata fetcher's XQuery, which resolves a slug to a page without
+* shipping the whole tree. Both adapters live in this module so the rule
+* cannot drift. The only difference between them is how "no prefix" is
+* spelled: `undefined` in TypeScript, the empty string in XQuery, which has no
+* way to pass an absent argument.
+*/
+/**
+* The prefix OCHRE puts on a segment page's slug to keep it unique
+*/
+const SEGMENT_UNIQUE_SLUG_PREFIX_PATTERN = String.raw`^\$[^-]*-`;
+/**
+* The separator between a slug and its prefix
+*/
+const WEBSITE_PAGE_SLUG_SEPARATOR = "/";
+const SEGMENT_UNIQUE_SLUG_PREFIX_REGEX = new RegExp(SEGMENT_UNIQUE_SLUG_PREFIX_PATTERN);
+/**
+* Strip the uniqueness prefix from a website page slug
+* @param slug - The raw slug
+* @returns The cleaned slug, or null when there was none
+* @internal
+*/
+function cleanWebsitePageSlug(slug) {
+	return slug?.replace(SEGMENT_UNIQUE_SLUG_PREFIX_REGEX, "") ?? null;
+}
+/**
+* Join a website page slug onto the slug of the segment holding it
+* @param slug - The page slug
+* @param slugPrefix - The slug of the enclosing segment, if any
+* @returns The full slug
+* @internal
+*/
+function prefixSlug(slug, slugPrefix) {
+	if (slugPrefix === "" || slugPrefix == null) return slug;
+	if (slug === "") return slugPrefix;
+	return `${slugPrefix}/${slug}`;
+}
+/**
+* The slug a page gives its own child pages
+*
+* A page only prefixes its children once it is itself inside a segment, so a
+* top-level website keeps flat page slugs.
+* @param pageSlug - The page's own full slug
+* @param slugPrefix - The prefix the page was resolved with
+* @returns The prefix for the page's children, or undefined for no prefix
+* @internal
+*/
+function childSlugPrefix(pageSlug, slugPrefix) {
+	return slugPrefix == null ? void 0 : pageSlug;
+}
+/**
+* The XQuery counterpart of {@link cleanWebsitePageSlug},
+* {@link prefixSlug} and {@link childSlugPrefix}
+*
+* Declares `local:clean-slug`, `local:page-slug` and
+* `local:page-child-slug-prefix`. "No prefix" is the empty string here.
+* @internal
+*/
+const WEBSITE_PAGE_SLUG_DECLARATIONS = `declare function local:clean-slug($slug) {
+  replace(string($slug), ${stringLiteral(SEGMENT_UNIQUE_SLUG_PREFIX_PATTERN)}, "")
+};
+
+declare function local:page-slug($resource, $slug-prefix) {
+  let $slug := local:clean-slug($resource/@slug)
+  return
+    if ($slug-prefix = "") then $slug
+    else if ($slug = "") then $slug-prefix
+    else concat($slug-prefix, ${stringLiteral("/")}, $slug)
+};
+
+declare function local:page-child-slug-prefix($resource, $slug-prefix) {
+  if ($slug-prefix = "") then ""
+  else local:page-slug($resource, $slug-prefix)
+};
+`;
+//#endregion
+export { SEGMENT_UNIQUE_SLUG_PREFIX_PATTERN, WEBSITE_PAGE_SLUG_DECLARATIONS, WEBSITE_PAGE_SLUG_SEPARATOR, childSlugPrefix, cleanWebsitePageSlug, prefixSlug };

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

@@ -0,0 +1,28 @@
+import { ResponsiveStyles, StylesheetItem } from "../../types/website.mjs";
+import { SimplifiedProperty } from "../../types/index.mjs";
+import { XMLWebsiteStyle } from "../../xml/types.mjs";
+//#region src/parsers/website/styles.d.ts
+/**
+ * The CSS declarations for every viewport a resource defines
+ * @param properties - Array of properties to parse
+ * @returns The styles per viewport
+ * @internal
+ */
+export declare function parseResponsiveCssStyles<T extends ReadonlyArray<string>>(properties: ReadonlyArray<SimplifiedProperty<T>>): ResponsiveStyles;
+/**
+ * An empty set of responsive styles, for resources that define none
+ * @returns The empty styles
+ * @internal
+ */
+export declare function emptyResponsiveStyles(): ResponsiveStyles;
+/**
+ * The stylesheet a website attaches to a property variable or value
+ *
+ * OCHRE has no viewport dimension on stylesheet entries, so these only ever
+ * carry default styles, unlike the per-element styles above.
+ * @param styles - The raw stylesheet entries
+ * @returns The parsed stylesheet items
+ * @internal
+ */
+export declare function parseStylesheets(styles: Array<XMLWebsiteStyle>): Array<StylesheetItem>;
+//#endregion

package/dist/parsers/website/styles.mjs

@@ -0,0 +1,103 @@
+import { getProperty } from "../../getters.mjs";
+//#region src/parsers/website/styles.ts
+const STYLESHEET_NON_STYLE_KEYS = /* @__PURE__ */ new Set([
+	"variableUuid",
+	"valueUuid",
+	"category",
+	"payload",
+	"content"
+]);
+/**
+* The CSS declarations a presentation variant carries
+*
+* @param properties - Array of properties to parse
+* @param cssVariant - CSS variant to parse
+* @returns Array of CSS styles
+*/
+function parseCssStylesFromProperties(properties, cssVariant) {
+	const cssProperties = getProperty(properties, {
+		label: "presentation",
+		valueContent: cssVariant != null ? `css-${cssVariant}` : "css"
+	})?.properties ?? [];
+	const styles = [];
+	for (const property of cssProperties) {
+		const value = property.values[0]?.content.toString();
+		if (value != null) styles.push({
+			label: property.variable.label,
+			value
+		});
+	}
+	return styles;
+}
+/**
+* The CSS declarations for every viewport a resource defines
+* @param properties - Array of properties to parse
+* @returns The styles per viewport
+* @internal
+*/
+function parseResponsiveCssStyles(properties) {
+	return {
+		default: parseCssStylesFromProperties(properties),
+		tablet: parseCssStylesFromProperties(properties, "tablet"),
+		mobile: parseCssStylesFromProperties(properties, "mobile")
+	};
+}
+/**
+* An empty set of responsive styles, for resources that define none
+* @returns The empty styles
+* @internal
+*/
+function emptyResponsiveStyles() {
+	return {
+		default: [],
+		tablet: [],
+		mobile: []
+	};
+}
+/**
+* The stylesheet a website attaches to a property variable or value
+*
+* OCHRE has no viewport dimension on stylesheet entries, so these only ever
+* carry default styles, unlike the per-element styles above.
+* @param styles - The raw stylesheet entries
+* @returns The parsed stylesheet items
+* @internal
+*/
+function parseStylesheets(styles) {
+	const parsedStyles = [];
+	for (const style of styles) {
+		const defaultStyles = [];
+		for (const [label, value] of Object.entries(style)) {
+			if (STYLESHEET_NON_STYLE_KEYS.has(label)) continue;
+			const valueString = value?.toString();
+			if (valueString != null) defaultStyles.push({
+				label,
+				value: valueString
+			});
+		}
+		const stylesByViewport = {
+			...emptyResponsiveStyles(),
+			default: defaultStyles
+		};
+		if (style.category === "propertyValue" || style.valueUuid != null) {
+			if (style.valueUuid == null) throw new Error(`Stylesheet property value "${style.variableUuid}" is missing a value UUID`, { cause: style });
+			parsedStyles.push({
+				uuid: style.valueUuid,
+				category: "propertyValue",
+				variableUuid: style.variableUuid,
+				icon: style.lucideIcon ?? null,
+				styles: stylesByViewport
+			});
+			continue;
+		}
+		parsedStyles.push({
+			uuid: style.variableUuid,
+			category: "propertyVariable",
+			icon: style.lucideIcon ?? null,
+			styles: stylesByViewport
+		});
+	}
+	return parsedStyles;
+}
+//#endregion
+export { emptyResponsiveStyles, parseResponsiveCssStyles, parseStylesheets };

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

@@ -0,0 +1,68 @@
+import { XMLWebsiteResource, XMLWebsiteResourceItem, XMLWebsiteTree } from "../../xml/types.mjs";
+import { ParserOptions } from "../helpers.mjs";
+import { WebsitePageSlugs } from "./slug.mjs";
+//#region src/parsers/website/walk.d.ts
+/**
+ * A page in a website, with its slug already resolved
+ *
+ * OCHRE stores a page's slug relative to the segment holding it, so the full
+ * slug depends on the path taken to reach the page. That path is walked once,
+ * here, and both the page parser and the slug map read the result instead of
+ * each re-deriving it.
+ * @internal
+ */
+export type WebsitePageNode = {
+  resource: XMLWebsiteResource;
+  slug: string;
+  children: Array<WebsitePageNode>;
+  segments: Array<{
+    tree: XMLWebsiteTree;
+    slugPrefix: string;
+  }>;
+};
+/**
+ * Flatten the wrapper elements OCHRE nests resources in
+ *
+ * A `<resource>` holding only more resources is grouping, not content. Note
+ * that this drops segment wrappers, which carry neither an identification nor
+ * a nested resource list; {@link readWebsitePages} picks those up separately,
+ * because a segment becomes its own website rather than a resource.
+ * @param resources - The raw resource items
+ * @returns The identified resources, in source order
+ * @internal
+ */
+export declare function normalizeWebsiteResources(resources: Array<XMLWebsiteResourceItem> | undefined): Array<XMLWebsiteResource>;
+/**
+ * The pages directly under a set of resources, and everything under them
+ *
+ * Only pages carry routes, so this descends through pages and the segments
+ * they hold and stops at anything else. Blocks and elements are the page's
+ * content and are parsed by the page, not walked for further pages.
+ * @param resources - The raw resource items to read
+ * @param options - Parser options
+ * @param slugPrefix - The slug of the enclosing segment, if any
+ * @returns The page nodes, in source order
+ * @internal
+ */
+export declare function readWebsitePages<T extends ReadonlyArray<string>>(resources: Array<XMLWebsiteResourceItem> | undefined, options: ParserOptions<T>, slugPrefix?: string): Array<WebsitePageNode>;
+/**
+ * Every page's full slug, keyed by UUID, including pages inside segments
+ * @param pages - The page nodes to collect from
+ * @param options - Parser options
+ * @param pageSlugsByUuid - The map to fill, for the recursive calls
+ * @returns The filled map
+ * @internal
+ */
+export declare function collectWebsitePageSlugs<T extends ReadonlyArray<string>>(pages: ReadonlyArray<WebsitePageNode>, options: ParserOptions<T>, pageSlugsByUuid?: Map<string, string>): WebsitePageSlugs;
+/**
+ * The XQuery counterpart of {@link normalizeWebsiteResources} and the page
+ * descent in {@link readWebsitePages}
+ *
+ * Declares `local:resource-items`, `local:presentation` and, from
+ * {@link WEBSITE_PAGE_SLUG_DECLARATIONS}, the slug rules. Segment wrappers are
+ * kept here rather than dropped, because the caller filters for pages by
+ * presentation and reads segments off the same sequence.
+ * @internal
+ */
+export declare const WEBSITE_WALK_DECLARATIONS: string;
+//#endregion

package/dist/parsers/website/walk.mjs

@@ -0,0 +1,116 @@
+import { parseStringContent } from "../helpers.mjs";
+import { parseSimplifiedProperties } from "../index.mjs";
+import { stringLiteral } from "../../xquery.mjs";
+import { formatXMLWebsiteResourceMetadata } from "./messages.mjs";
+import { websitePresentationReader } from "./reader.mjs";
+import { WEBSITE_PAGE_SLUG_DECLARATIONS, childSlugPrefix, cleanWebsitePageSlug, prefixSlug } from "./slug.mjs";
+//#region src/parsers/website/walk.ts
+/**
+* Flatten the wrapper elements OCHRE nests resources in
+*
+* A `<resource>` holding only more resources is grouping, not content. Note
+* that this drops segment wrappers, which carry neither an identification nor
+* a nested resource list; {@link readWebsitePages} picks those up separately,
+* because a segment becomes its own website rather than a resource.
+* @param resources - The raw resource items
+* @returns The identified resources, in source order
+* @internal
+*/
+function normalizeWebsiteResources(resources) {
+	const normalized = [];
+	const resourcesToNormalize = resources ?? [];
+	for (const resource of resourcesToNormalize) {
+		if ("identification" in resource) {
+			normalized.push(resource);
+			continue;
+		}
+		if ("resource" in resource) normalized.push(...resource.resource);
+	}
+	return normalized;
+}
+function readWebsiteSegments(resources, options, slugPrefix) {
+	const segments = [];
+	const segmentResources = resources ?? [];
+	for (const resource of segmentResources) {
+		if (!("segments" in resource)) continue;
+		for (const tree of resource.segments.tree) {
+			const segmentSlug = tree.identification.abbreviation == null ? null : parseStringContent(tree.identification.abbreviation, options);
+			if (segmentSlug == null) throw new Error(`Slug not found for segment website (website uuid “${tree.uuid}”)`, { cause: tree });
+			segments.push({
+				tree,
+				slugPrefix: prefixSlug(segmentSlug, slugPrefix)
+			});
+		}
+	}
+	return segments;
+}
+/**
+* The pages directly under a set of resources, and everything under them
+*
+* Only pages carry routes, so this descends through pages and the segments
+* they hold and stops at anything else. Blocks and elements are the page's
+* content and are parsed by the page, not walked for further pages.
+* @param resources - The raw resource items to read
+* @param options - Parser options
+* @param slugPrefix - The slug of the enclosing segment, if any
+* @returns The page nodes, in source order
+* @internal
+*/
+function readWebsitePages(resources, options, slugPrefix) {
+	const pages = [];
+	for (const resource of normalizeWebsiteResources(resources)) {
+		const properties = parseSimplifiedProperties(resource.properties, options);
+		if (websitePresentationReader(properties).value("presentation") !== "page") continue;
+		const slug = cleanWebsitePageSlug(resource.slug);
+		if (slug == null) throw new Error(`Slug not found for page (${formatXMLWebsiteResourceMetadata(resource)})`, { cause: resource });
+		const pageSlug = prefixSlug(slug, slugPrefix);
+		pages.push({
+			resource,
+			slug: pageSlug,
+			children: readWebsitePages(resource.resource, options, childSlugPrefix(pageSlug, slugPrefix)),
+			segments: readWebsiteSegments(resource.resource, options, pageSlug)
+		});
+	}
+	return pages;
+}
+/**
+* Every page's full slug, keyed by UUID, including pages inside segments
+* @param pages - The page nodes to collect from
+* @param options - Parser options
+* @param pageSlugsByUuid - The map to fill, for the recursive calls
+* @returns The filled map
+* @internal
+*/
+function collectWebsitePageSlugs(pages, options, pageSlugsByUuid = /* @__PURE__ */ new Map()) {
+	for (const page of pages) {
+		pageSlugsByUuid.set(page.resource.uuid, page.slug);
+		collectWebsitePageSlugs(page.children, options, pageSlugsByUuid);
+		for (const segment of page.segments) collectWebsitePageSlugs(readWebsitePages(segment.tree.items?.resource, options, segment.slugPrefix), options, pageSlugsByUuid);
+	}
+	return pageSlugsByUuid;
+}
+/**
+* The XQuery counterpart of {@link normalizeWebsiteResources} and the page
+* descent in {@link readWebsitePages}
+*
+* Declares `local:resource-items`, `local:presentation` and, from
+* {@link WEBSITE_PAGE_SLUG_DECLARATIONS}, the slug rules. Segment wrappers are
+* kept here rather than dropped, because the caller filters for pages by
+* presentation and reads segments off the same sequence.
+* @internal
+*/
+const WEBSITE_WALK_DECLARATIONS = `declare function local:resource-items($resources) {
+  for $resource in $resources
+  return
+    if ($resource/segments) then $resource
+    else if ($resource/identification) then $resource
+    else local:resource-items($resource/resource)
+};
+
+declare function local:presentation($resource) {
+  string(($resource/properties/property[label/string() = ${stringLiteral("presentation")}]/value)[1])
+};
+
+${WEBSITE_PAGE_SLUG_DECLARATIONS}`;
+//#endregion
+export { WEBSITE_WALK_DECLARATIONS, collectWebsitePageSlugs, normalizeWebsiteResources, readWebsitePages };

package/dist/query.d.mts

@@ -1,24 +1,20 @@
-import { Query } from "./types/index.mjs";
+import { PropertyRelation, Query } from "./types/index.mjs";
+import { OchreQueryContext } from "./xquery.mjs";
 //#region src/query.d.ts
-export declare function buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids: Array<string>, belongsToCollectionPropertyVariableUuid: string): string | null;
+export declare function buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids: ReadonlyArray<string>, belongsToCollectionPropertyVariableUuid: string): string | null;
 /**
- * Compile a query tree into the XQuery `let` clauses that bind `$items` to the
- * matching Set items
+ * Compile a query tree into the clauses that bind 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`
+ * 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;
+ * 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
+ * @param parameters.baseItemsExpression - The inline searchable path to filter
+ * @param parameters.scopeQueryExpression - An extra query AND-ed into every search
+ * @returns The prolog, the clauses binding the items, and the bound CTS queries
+ * @internal
  */
 export declare function buildQueryPlan(parameters: {
   queries: Query | null;
@@ -27,5 +23,57 @@ export declare function buildQueryPlan(parameters: {
 }): {
   prolog: string;
   itemsClause: string;
+  itemsVariable: string;
+  queryBindings: Array<{
+    name: string;
+    expression: string;
+  }>;
 };
+/**
+ * Compile a Set item query 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.
+ * @param parameters - The query parameters
+ * @param parameters.setScopeUuids - The Set scope 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
+ * @param parameters.body - Builds the body from the name of the variable holding the items
+ * @returns A complete XQuery document
+ * @internal
+ */
+export declare function compileSetItemsQuery(parameters: {
+  setScopeUuids: ReadonlyArray<string>;
+  belongsToCollectionScopeUuids: ReadonlyArray<string>;
+  queries: Query | null;
+  declarations?: ReadonlyArray<string>;
+  body: (context: OchreQueryContext & {
+    items: string;
+  }) => string;
+}): string;
+/**
+ * Reduce a property-value facet query tree to the leaves that filter items
+ *
+ * A facet request carries property leaves that name a variable without naming
+ * a value, which select what to aggregate rather than which items to keep.
+ * Those are dropped, and groups left with a single child collapse into it.
+ * @param queries - The query tree to reduce
+ * @returns The reduced tree, or null when nothing filters items
+ * @internal
+ */
+export declare function getItemFilterQueries(queries: Query | null): Query | null;
+/**
+ * Collect the property variables a query tree asks to be aggregated
+ * @param queries - The query tree to walk
+ * @returns One selector per distinct property variable and relation pair
+ * @internal
+ */
+export declare function getPropertyFacetSelectors(queries: Query | null): Array<{
+  uuid: string;
+  relation: PropertyRelation | null;
+}>;
 //#endregion