ochre-sdk 1.0.78 → 1.1.0

package/dist/types/index.d.mts

@@ -1,7 +1,7 @@
 import { MultilingualString } from "../parsers/multilingual.mjs";
+import { Prettify } from "./utilities.mjs";
 import { Webpage } from "./website.mjs";
 //#region src/types/index.d.ts
-export type Prettify<T> = { [K in keyof T]: T[K]; } & {};
 /**
  * Language-code tuple or array used by OCHRE multilingual fields.
  *
@@ -38,10 +38,6 @@ export type ContainedItemCategoryFromOption<U extends ItemCategory = ItemCategor
  * The category of items in a heading
  */
 export type HeadingItemCategory = Exclude<ItemCategory, "tree" | "bibliography" | "spatialUnit" | "concept" | "period">;
-/**
- * The category of items that expose recursive subitem structures.
- */
-export type RecursiveItemCategory = Exclude<ItemCategory, "tree" | "person" | "propertyVariable" | "propertyValue" | "set">;
 /**
  *  The category names that can appear in OCHRE context paths
  */
@@ -365,7 +361,6 @@ export type SimplifiedProperty<T extends LanguageCodes = LanguageCodes> = {
 export type SetItemProperty<T extends LanguageCodes = LanguageCodes> = Omit<Property<T>, "properties">;
 export type SetItemSimplifiedProperty<T extends LanguageCodes = LanguageCodes> = Omit<SimplifiedProperty<T>, "properties">;
 export type PropertyLike<T extends LanguageCodes = LanguageCodes> = Property<T> | SetItemProperty<T> | SimplifiedProperty<T> | SetItemSimplifiedProperty<T>;
-export type ItemProperty<T extends LanguageCodes = LanguageCodes> = Property<T> | SetItemProperty<T>;
 export type PropertyValueDataType = PropertyValueContent["dataType"];
 export type QueryablePropertyValueDataType = Exclude<PropertyValueDataType, "coordinate">;
 export type PropertyRelation = "related" | "inverse";
@@ -502,9 +497,6 @@ export type Item<U extends ItemCategory = ItemCategory, V extends ContainedItemC
  * An item fetched without its embedded item hierarchy.
  */
 export type ItemWithoutEmbeddedItems<U extends ItemCategoryWithEmbeddedItems = ItemCategoryWithEmbeddedItems, V extends ContainedItemCategory<U> = ContainedItemCategory<U>, T extends LanguageCodes = LanguageCodes, W extends ItemPayloadKind = "topLevel"> = U extends ItemCategoryWithEmbeddedItems ? U extends "tree" ? Prettify<Omit<Tree<Extract<V, TreeItemCategory>, T, W>, "items">> : U extends "set" ? Prettify<Omit<Set<Extract<V, SetItemCategory>, T, W>, "items">> : U extends "bibliography" ? Prettify<Omit<Bibliography<T, W>, "items">> : U extends "concept" ? Prettify<Omit<Concept<T, W>, "items">> : U extends "spatialUnit" ? Prettify<Omit<SpatialUnit<T, W>, "items">> : U extends "period" ? Prettify<Omit<Period<T, W>, "items">> : U extends "resource" ? Prettify<Omit<Resource<T, W>, "items">> : never : never;
-export type TopLevelItem<U extends ItemCategory = ItemCategory, V extends ContainedItemCategory<U> = ContainedItemCategory<U>, T extends LanguageCodes = LanguageCodes> = Item<U, V, T, "topLevel">;
-export type EmbeddedItem<U extends ItemCategory = ItemCategory, V extends ContainedItemCategory<U> = ContainedItemCategory<U>, T extends LanguageCodes = LanguageCodes> = Item<U, V, T, "embedded">;
-export type AnyItem<U extends ItemCategory = ItemCategory, V extends ContainedItemCategory<U> = ContainedItemCategory<U>, T extends LanguageCodes = LanguageCodes> = Item<U, V, T, ItemPayloadKind>;
 /**
  *  Heading in OCHRE
  */
@@ -748,28 +740,6 @@ export type Section<T extends LanguageCodes = LanguageCodes> = {
     identification: Identification<T>;
   } | null;
 };
-export type EmbeddedTree<U extends TreeItemCategory = TreeItemCategory, T extends LanguageCodes = LanguageCodes> = Tree<U, T, "embedded">;
-export type AnyTree<U extends TreeItemCategory = TreeItemCategory, T extends LanguageCodes = LanguageCodes> = Tree<U, T, ItemPayloadKind>;
-export type EmbeddedSet<U extends SetItemCategory = SetItemCategory, T extends LanguageCodes = LanguageCodes> = Set<U, T, "embedded">;
-export type AnySet<U extends SetItemCategory = SetItemCategory, T extends LanguageCodes = LanguageCodes> = Set<U, T, ItemPayloadKind>;
-export type EmbeddedBibliography<T extends LanguageCodes = LanguageCodes> = Bibliography<T, "embedded">;
-export type AnyBibliography<T extends LanguageCodes = LanguageCodes> = Bibliography<T, ItemPayloadKind>;
-export type EmbeddedConcept<T extends LanguageCodes = LanguageCodes> = Concept<T, "embedded">;
-export type AnyConcept<T extends LanguageCodes = LanguageCodes> = Concept<T, ItemPayloadKind>;
-export type EmbeddedSpatialUnit<T extends LanguageCodes = LanguageCodes> = SpatialUnit<T, "embedded">;
-export type AnySpatialUnit<T extends LanguageCodes = LanguageCodes> = SpatialUnit<T, ItemPayloadKind>;
-export type EmbeddedPeriod<T extends LanguageCodes = LanguageCodes> = Period<T, "embedded">;
-export type AnyPeriod<T extends LanguageCodes = LanguageCodes> = Period<T, ItemPayloadKind>;
-export type EmbeddedPerson<T extends LanguageCodes = LanguageCodes> = Person<T, "embedded">;
-export type AnyPerson<T extends LanguageCodes = LanguageCodes> = Person<T, ItemPayloadKind>;
-export type EmbeddedPropertyVariable<T extends LanguageCodes = LanguageCodes> = PropertyVariable<T, "embedded">;
-export type AnyPropertyVariable<T extends LanguageCodes = LanguageCodes> = PropertyVariable<T, ItemPayloadKind>;
-export type EmbeddedPropertyValue<T extends LanguageCodes = LanguageCodes> = PropertyValue<T, "embedded">;
-export type AnyPropertyValue<T extends LanguageCodes = LanguageCodes> = PropertyValue<T, ItemPayloadKind>;
-export type EmbeddedResource<T extends LanguageCodes = LanguageCodes> = Resource<T, "embedded">;
-export type AnyResource<T extends LanguageCodes = LanguageCodes> = Resource<T, ItemPayloadKind>;
-export type EmbeddedText<T extends LanguageCodes = LanguageCodes> = Text<T, "embedded">;
-export type AnyText<T extends LanguageCodes = LanguageCodes> = Text<T, ItemPayloadKind>;
 /**
  * Represents a gallery with its identification, project identification, resources and max length
  */

package/dist/types/utilities.d.mts

@@ -0,0 +1,9 @@
+//#region src/types/utilities.d.ts
+/**
+ * Flatten an intersection so editors show one object instead of `A & B`
+ *
+ * Deliberately not re-exported from the package root: it is a TypeScript
+ * presentation detail, not part of the OCHRE model.
+ */
+export type Prettify<T> = { [K in keyof T]: T[K]; } & {};
+//#endregion

package/dist/types/utilities.mjs

@@ -0,0 +1 @@
+export {};

package/dist/types/website.d.mts

@@ -1,5 +1,6 @@
 import { MultilingualString } from "../parsers/multilingual.mjs";
-import { Bibliography, Identification, ItemCategory, LanguageCodes, License, Metadata, Person, Prettify, QueryablePropertyValueDataType } from "./index.mjs";
+import { Prettify } from "./utilities.mjs";
+import { Bibliography, Identification, LanguageCodes, License, Metadata, Person, QueryablePropertyValueDataType } from "./index.mjs";
 //#region src/types/website.d.ts
 /**
  * Represents a context tree level item with a variable and value
@@ -64,28 +65,47 @@ export type WebOptions<T extends LanguageCodes = LanguageCodes> = {
   };
 };
 /**
- * Represents a stylesheet item with its UUID and category
+ * The style overrides for each viewport a website presentation targets
  */
-export type StylesheetCategory = Extract<ItemCategory, "propertyVariable" | "propertyValue">;
+export type ResponsiveStyles = {
+  default: Array<Style>;
+  tablet: Array<Style>;
+  mobile: Array<Style>;
+};
+/**
+ * Whether an item page section and its header are shown
+ */
+export type WebSectionDisplay = {
+  isDisplayed: boolean;
+  isHeaderDisplayed: boolean;
+};
+/**
+ * How a website indicates that content is loading
+ */
+export type WebLoadingVariant = "spinner" | "skeleton" | "animation" | "none";
+/**
+ * How an item page groups a repeated section
+ */
+export type WebSectionVariant = "discrete" | "tabs-horizontal" | "tabs-vertical" | "tabular";
+/**
+ * The IIIF viewer a website renders images with
+ */
+export type WebIiifViewer = "universal-viewer" | "clover";
+/**
+ * How a website restricts access to its content
+ */
+export type WebsitePrivacy = "public" | "password" | "credentials-ochre";
 export type StylesheetItem = {
   uuid: string;
   category: "propertyVariable";
   icon: string | null;
-  styles: {
-    default: Array<Style>;
-    tablet: Array<Style>;
-    mobile: Array<Style>;
-  };
+  styles: ResponsiveStyles;
 } | {
   uuid: string;
   category: "propertyValue";
   variableUuid: string;
   icon: string | null;
-  styles: {
-    default: Array<Style>;
-    tablet: Array<Style>;
-    mobile: Array<Style>;
-  };
+  styles: ResponsiveStyles;
 };
 export type WebsitePropertyQueryNode<T extends LanguageCodes = LanguageCodes> = {
   target: "property";
@@ -113,11 +133,7 @@ export type WebSidebar<T extends LanguageCodes = LanguageCodes> = {
   title: WebTitle<T>;
   layout: "start" | "end";
   mobileLayout: "default" | "inline";
-  cssStyles: {
-    default: Array<Style>;
-    tablet: Array<Style>;
-    mobile: Array<Style>;
-  };
+  cssStyles: ResponsiveStyles;
 };
 /**
  * Represents a website with its properties and items
@@ -139,12 +155,12 @@ export type Website<T extends LanguageCodes = LanguageCodes> = {
     type: WebsiteType;
     status: "development" | "preview" | "production";
     versionLabel: "experimental" | "alpha" | "beta" | "test" | "staging" | "pre-release" | "release";
-    privacy: "public" | "password" | "credentials-ochre";
+    privacy: WebsitePrivacy;
     contact: {
       name: string;
       email: string | null;
     } | null;
-    loadingVariant: "spinner" | "skeleton" | "animation" | "none";
+    loadingVariant: WebLoadingVariant;
     theme: {
       isThemeToggleDisplayed: boolean;
       defaultTheme: "light" | "dark" | "system";
@@ -170,37 +186,25 @@ export type Website<T extends LanguageCodes = LanguageCodes> = {
     sidebar: WebSidebar<T> | null;
     itemPage: {
       isMainContentDisplayed: boolean;
-      description: {
-        isDisplayed: boolean;
-        isHeaderDisplayed: boolean;
-      };
-      document: {
-        isDisplayed: boolean;
-        isHeaderDisplayed: boolean;
-      };
+      description: WebSectionDisplay;
+      document: WebSectionDisplay;
       notes: {
         isDisplayed: boolean;
         isHeaderDisplayed: boolean;
-        variant: "discrete" | "tabs-horizontal" | "tabs-vertical" | "tabular";
+        variant: WebSectionVariant;
       };
       events: {
         isDisplayed: boolean;
         isHeaderDisplayed: boolean;
-        variant: "discrete" | "tabs-horizontal" | "tabs-vertical" | "tabular";
-      };
-      periods: {
-        isDisplayed: boolean;
-        isHeaderDisplayed: boolean;
+        variant: WebSectionVariant;
       };
+      periods: WebSectionDisplay;
       isPropertiesDisplayed: boolean;
-      bibliography: {
-        isDisplayed: boolean;
-        isHeaderDisplayed: boolean;
-      };
+      bibliography: WebSectionDisplay;
       isPropertyValuesGrouped: boolean;
       isPublicationDateTimeDisplayed: boolean;
       isPersistentIdentifierDisplayed: boolean;
-      iiifViewer: "universal-viewer" | "clover";
+      iiifViewer: WebIiifViewer;
     };
     options: Prettify<WebOptions<T> & {
       stylesheets: {
@@ -245,11 +249,7 @@ export type Webpage<T extends LanguageCodes = LanguageCodes> = {
     } | null;
     backgroundImage: WebImage<T> | null;
     sidebar: WebSidebar<T> | null;
-    cssStyles: {
-      default: Array<Style>;
-      tablet: Array<Style>;
-      mobile: Array<Style>;
-    };
+    cssStyles: ResponsiveStyles;
   };
   webpages: Array<Webpage<T>>;
 };
@@ -275,11 +275,7 @@ export type WebElement<T extends LanguageCodes = LanguageCodes> = {
   language: string | null;
   type: "element";
   title: WebTitle<T>;
-  cssStyles: {
-    default: Array<Style>;
-    tablet: Array<Style>;
-    mobile: Array<Style>;
-  };
+  cssStyles: ResponsiveStyles;
 } & WebElementComponent<T>;
 /**
  * Union type of all possible web element components
@@ -342,7 +338,7 @@ export type WebElementComponent<T extends LanguageCodes = LanguageCodes> = {
   }> | null;
   variant: "slide" | "table" | "card" | "tile" | "showcase";
   paginationVariant: "default" | "numeric";
-  loadingVariant: "spinner" | "skeleton" | "animation" | "none";
+  loadingVariant: WebLoadingVariant;
   image: {
     layout: "top" | "bottom" | "start" | "end" | null;
     fit: "fill" | "fit";
@@ -377,7 +373,7 @@ export type WebElementComponent<T extends LanguageCodes = LanguageCodes> = {
 } | {
   component: "iiif-viewer";
   linkUuid: string;
-  variant: "universal-viewer" | "clover";
+  variant: WebIiifViewer;
 } | {
   component: "image";
   images: Array<WebImage<T>>;
@@ -529,14 +525,9 @@ export type WebBlock<T extends LanguageCodes = LanguageCodes, U extends WebBlock
     tablet: Partial<WebBlock<T>["properties"]["default"]> | null;
     mobile: Partial<WebBlock<T>["properties"]["default"]> | null;
   };
-  cssStyles: {
-    default: Array<Style>;
-    tablet: Array<Style>;
-    mobile: Array<Style>;
-  };
+  cssStyles: ResponsiveStyles;
 };
 export type WebBlockByLayout<U extends WebBlockLayout = WebBlockLayout, T extends LanguageCodes = LanguageCodes> = WebBlock<T, U>;
-export type AccordionWebBlock<T extends LanguageCodes = LanguageCodes> = WebBlock<T, "accordion">;
 export type WebsiteMetadata<T extends LanguageCodes = LanguageCodes> = {
   uuid: string;
   belongsTo: {
@@ -547,7 +538,7 @@ export type WebsiteMetadata<T extends LanguageCodes = LanguageCodes> = {
   description: string;
   webpageTitle: MultilingualString<T> | null;
   properties: {
-    privacy: "public" | "password" | "credentials-ochre";
+    privacy: WebsitePrivacy;
     icon: {
       faviconUuid: string | null;
       appleTouchIconUuid: string | null;

package/dist/xml/metadata.d.mts

@@ -1,4 +1,20 @@
 //#region src/xml/metadata.d.ts
+/**
+ * Read the offset a node started at in the source XML
+ * @param value - The parsed node
+ * @returns The offset, or null when the node carries no source metadata
+ * @internal
+ */
 export declare function getXMLSourceIndex(value: unknown): number | null;
+/**
+ * Re-attach the source metadata validation dropped
+ *
+ * `v.safeParse` returns a fresh object graph and does not carry over the
+ * non-enumerable symbol `fast-xml-parser` records offsets under, so it is
+ * grafted back on by walking the validated output alongside the raw input.
+ * @param output - The validated output to graft onto
+ * @param input - The raw parsed input to read metadata from
+ * @internal
+ */
 export declare function restoreXMLMetadata(output: unknown, input: unknown): void;
 //#endregion

package/dist/xml/metadata.mjs

@@ -1,21 +1,42 @@
+import { isObject, readEntries, readProperty } from "../reflection.mjs";
 import { XMLParser } from "fast-xml-parser";
 //#region src/xml/metadata.ts
 const XML_METADATA_SYMBOL = XMLParser.getMetaDataSymbol();
-function isRecord(value) {
-	return typeof value === "object" && value != null;
-}
-function getXMLMetadata(value) {
-	if (!isRecord(value)) return null;
-	return value[XML_METADATA_SYMBOL] ?? null;
+/**
+* Read the source metadata `fast-xml-parser` attaches under a symbol key
+*
+* Returned as `unknown`: nothing here needs to know its shape, only whether it
+* is there, and {@link getXMLSourceIndex} narrows the one field it reads.
+* @param value - The value to read from
+* @returns The metadata, or undefined when there is none
+*/
+function readXMLMetadata(value) {
+	return readProperty(value, XML_METADATA_SYMBOL);
 }
+/**
+* Read the offset a node started at in the source XML
+* @param value - The parsed node
+* @returns The offset, or null when the node carries no source metadata
+* @internal
+*/
 function getXMLSourceIndex(value) {
-	const startIndex = getXMLMetadata(value)?.startIndex;
+	const startIndex = readProperty(readXMLMetadata(value), "startIndex");
 	return typeof startIndex === "number" ? startIndex : null;
 }
+/**
+* Re-attach the source metadata validation dropped
+*
+* `v.safeParse` returns a fresh object graph and does not carry over the
+* non-enumerable symbol `fast-xml-parser` records offsets under, so it is
+* grafted back on by walking the validated output alongside the raw input.
+* @param output - The validated output to graft onto
+* @param input - The raw parsed input to read metadata from
+* @internal
+*/
 function restoreXMLMetadata(output, input) {
-	if (!isRecord(output) || !isRecord(input)) return;
-	const metadata = getXMLMetadata(input);
-	if (metadata != null) Object.defineProperty(output, XML_METADATA_SYMBOL, {
+	if (!isObject(output) || !isObject(input)) return;
+	const metadata = readXMLMetadata(input);
+	if (metadata !== void 0) Object.defineProperty(output, XML_METADATA_SYMBOL, {
 		value: metadata,
 		enumerable: false,
 		configurable: true
@@ -24,7 +45,7 @@ function restoreXMLMetadata(output, input) {
 		for (const [index, outputValue] of output.entries()) restoreXMLMetadata(outputValue, input[index]);
 		return;
 	}
-	for (const [key, outputValue] of Object.entries(output)) restoreXMLMetadata(outputValue, input[key]);
+	for (const [key, outputValue] of readEntries(output)) restoreXMLMetadata(outputValue, readProperty(input, key));
 }
 //#endregion
 export { getXMLSourceIndex, restoreXMLMetadata };