cozy-iiif 0.1.4 → 0.1.6

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import { Manifest, Canvas, ImageService2, ImageService3, IIIFExternalWebResource, Collection } from '@iiif/presentation-3';
+import { Manifest, Canvas, ImageService2, ImageService3, IIIFExternalWebResource, Collection, Range, AnnotationPage } from '@iiif/presentation-3';
 export type CozyParseResult = {
     type: 'collection';
     url: string;
@@ -41,15 +41,26 @@ export interface CozyManifest {
     readonly source: Manifest;
     readonly id: string;
     readonly canvases: CozyCanvas[];
+    readonly structure: CozyRange[];
     getLabel(locale?: string): string | undefined;
+    getTableOfContents(): CozyTOCNode[];
     getMetadata(locale?: string): CozyMetadata[];
 }
+export interface CozyRange {
+    readonly source: Range;
+    readonly id: string;
+    readonly items: (CozyCanvas | CozyRange)[];
+    readonly canvases: CozyCanvas[];
+    readonly ranges: CozyRange[];
+    getLabel(locale?: string): string | undefined;
+}
 export interface CozyCanvas {
     readonly source: Canvas;
     readonly id: string;
     readonly width: number;
     readonly height: number;
     readonly images: CozyImageResource[];
+    readonly annotations: AnnotationPage[];
     getLabel(locale?: string): string;
     getMetadata(locale?: string): CozyMetadata[];
     getThumbnailURL(minSize?: number): string;
@@ -58,6 +69,14 @@ export interface CozyMetadata {
     readonly label: string;
     readonly value: string;
 }
+export interface CozyTOCNode {
+    readonly id: string;
+    readonly type: 'range' | 'canvas';
+    getLabel(locale?: string): string | undefined;
+    children: CozyTOCNode[];
+    parent?: CozyTOCNode;
+    level: number;
+}
 export type CozyImageResource = StaticImageResource | ImageServiceResource;
 export type ImageServiceResource = DynamicImageServiceResource | Level0ImageServiceResource;
 interface BaseImageResource {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cozy-iiif",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "A developer-friendly collection of abstractions and utilities built on top of @iiif/presentation-3 and @iiif/parser",
   "license": "MIT",
   "author": "Rainer Simon",
@@ -27,13 +27,14 @@
     "./level-0": "./dist/level-0/index.js"
   },
   "devDependencies": {
-    "vite": "^6.2.2",
+    "vite": "^6.2.5",
     "vite-plugin-dts": "^4.5.3",
-    "vitest": "^3.0.8"
+    "vitest": "^3.1.1"
   },
   "dependencies": {
     "@iiif/parser": "^2.1.7",
     "@iiif/presentation-3": "^2.2.3",
-    "p-throttle": "^7.0.0"
+    "p-throttle": "^7.0.0",
+    "uuid": "^11.1.0"
   }
 }

package/src/Cozy.ts

@@ -1,11 +1,13 @@
-import type { Canvas, Collection, Manifest } from '@iiif/presentation-3';
+import type { Canvas, Collection, Manifest, Range } from '@iiif/presentation-3';
 import { convertPresentation2  } from '@iiif/parser/presentation-2';
 import { Traverse } from '@iiif/parser';
+import * as Helpers from './helpers';
 import { 
   getImages, 
   getLabel, 
   getMetadata, 
   getPropertyValue, 
+  getTableOfContents,
   getThumbnailURL, 
   normalizeServiceUrl, 
   parseImageService 
@@ -16,126 +18,125 @@ import type {
   CozyCollectionItem, 
   CozyManifest, 
   CozyParseResult, 
+  CozyRange, 
   ImageServiceResource 
 } from './types';
 
-export const Cozy = {
-  
-  parseURL: async (input: string): Promise<CozyParseResult> => {
-    try {
-      new URL(input);
-    } catch {
-      return {
-        type: 'error',
-        code: 'INVALID_URL',
-        message: 'The provided input is not a valid URL'
-      };
-    }
+const parseURL = async (input: string): Promise<CozyParseResult> => {
+  try {
+    new URL(input);
+  } catch {
+    return {
+      type: 'error',
+      code: 'INVALID_URL',
+      message: 'The provided input is not a valid URL'
+    };
+  }
 
-    let response: Response;
+  let response: Response;
 
-    try {
-      response = await fetch(input);
-      if (!response.ok) {
-        return {
-          type: 'error',
-          code: 'INVALID_HTTP_RESPONSE',
-          message: `Server responded: HTTP ${response.status} ${response.statusText ? `(${response.statusText})` : ''}`
-        }
-      }
-    } catch (error) {
+  try {
+    response = await fetch(input);
+    if (!response.ok) {
       return {
         type: 'error',
-        code: 'FETCH_ERROR',
-        message: error instanceof Error ? error.message : 'Failed to fetch resource'
-      };
+        code: 'INVALID_HTTP_RESPONSE',
+        message: `Server responded: HTTP ${response.status} ${response.statusText ? `(${response.statusText})` : ''}`
+      }
     }
+  } catch (error) {
+    return {
+      type: 'error',
+      code: 'FETCH_ERROR',
+      message: error instanceof Error ? error.message : 'Failed to fetch resource'
+    };
+  }
 
-    const contentType = response.headers.get('content-type');
-    
-    if (contentType?.startsWith('image/')) {
-      return {
-        type: 'plain-image',
-        url: input
-      };
-    }
+  const contentType = response.headers.get('content-type');
+  
+  if (contentType?.startsWith('image/')) {
+    return {
+      type: 'plain-image',
+      url: input
+    };
+  }
 
-    if (contentType?.includes('text/html')) {
-      return {
-        type: 'webpage',
-        url: input
-      };
-    }
+  if (contentType?.includes('text/html')) {
+    return {
+      type: 'webpage',
+      url: input
+    };
+  }
 
-    try {
-      const json = await response.json();
-
-      const context = Array.isArray(json['@context'])
-        ? json['@context'].find(str => str.includes('iiif.io/api/'))
-        : json['@context'];
-
-      if (!context) {
-        return {
-          type: 'error',
-          code: 'INVALID_MANIFEST', 
-          message: 'Missing @context'
-        }
-      };
-
-      const id = getPropertyValue<string>(json, 'id');
-
-      if (!id) {
-        return { 
-          type: 'error',
-          code: 'INVALID_MANIFEST', 
-          message: 'Missing id property' 
-        }
-      }
+  try {
+    const json = await response.json();
+    return parse(json, input);
+  } catch {
+    return {
+      type: 'error',
+      code: 'UNSUPPORTED_FORMAT',
+      message: 'Could not parse resource'
+    };
+  }
+}
 
-      if (context.includes('presentation/2') || context.includes('presentation/3')) {
-        const majorVersion = context.includes('presentation/2') ? 2 : 3;
+const parse = (json: any, url?: string): CozyParseResult => {
+  const context = Array.isArray(json['@context'])
+    ? json['@context'].find(str => str.includes('iiif.io/api/'))
+    : json['@context'];
 
-        const type = getPropertyValue(json, 'type');
+  if (!context) {
+    return {
+      type: 'error',
+      code: 'INVALID_MANIFEST', 
+      message: 'Missing @context'
+    }
+  };
 
-        return type.includes('Collection') ? {
-          type: 'collection',
-          url: input,
-          resource: parseCollectionResource(json, majorVersion)
-        } : {
-          type: 'manifest',
-          url: input,
-          resource: parseManifestResource(json, majorVersion)
-        };
-      }
-      
-      if (context.includes('image/2') || context.includes('image/3')) {
-        const resource = parseImageResource(json);
-        return resource ? {
-          type: 'iiif-image',
-          url: input,
-          resource
-        } : {
-          type: 'error',
-          code: 'INVALID_MANIFEST',
-          message: 'Invalid image service definition'
-        }
-      }
+  const id = getPropertyValue<string>(json, 'id');
 
-      return {
-        type: 'error',
-        code: 'INVALID_MANIFEST',
-        message: 'JSON resource is not a recognized IIIF format'
-      };
-    } catch {
-      return {
-        type: 'error',
-        code: 'UNSUPPORTED_FORMAT',
-        message: 'Could not parse resource'
-      };
+  if (!id) {
+    return { 
+      type: 'error',
+      code: 'INVALID_MANIFEST', 
+      message: 'Missing id property' 
     }
+  }
+
+  if (context.includes('presentation/2') || context.includes('presentation/3')) {
+    const majorVersion = context.includes('presentation/2') ? 2 : 3;
+
+    const type = getPropertyValue(json, 'type');
 
+    return type.includes('Collection') ? {
+      type: 'collection',
+      url: url || id,
+      resource: parseCollectionResource(json, majorVersion)
+    } : {
+      type: 'manifest',
+      url: url || id,
+      resource: parseManifestResource(json, majorVersion)
+    };
+  }
+  
+  if (context.includes('image/2') || context.includes('image/3')) {
+    const resource = parseImageResource(json);
+    return resource ? {
+      type: 'iiif-image',
+      url: url || id,
+      resource
+    } : {
+      type: 'error',
+      code: 'INVALID_MANIFEST',
+      message: 'Invalid image service definition'
+    }
   }
 
+  return {
+    type: 'error',
+    code: 'INVALID_MANIFEST',
+    message: 'JSON resource is not a recognized IIIF format'
+  };
 }
 
 const parseCollectionResource = (resource: any, majorVersion: number): CozyCollection => {
@@ -174,15 +175,17 @@ const parseCollectionResource = (resource: any, majorVersion: number): CozyColle
 const parseManifestResource = (resource: any, majorVersion: number): CozyManifest => {
 
   const parseV3 = (manifest: Manifest) => {
-    const canvases: Canvas[] = [];
+    const sourceCanvases: Canvas[] = [];
+    const sourceRanges: Range[] = [];
 
     const modelBuilder = new Traverse({
-      canvas: [canvas => { if (canvas.items) canvases.push(canvas) }]
+      canvas: [canvas => { if (canvas.items) sourceCanvases.push(canvas) }],
+      range: [range => { if (range.type === 'Range') sourceRanges.push(range) }]
     });
   
     modelBuilder.traverseManifest(manifest);
     
-    return canvases.map((c: Canvas) => {
+    const canvases = sourceCanvases.map((c: Canvas) => {
       const images = getImages(c);
       return {
         source: c,
@@ -190,24 +193,55 @@ const parseManifestResource = (resource: any, majorVersion: number): CozyManifes
         width: c.width,
         height: c.height,
         images,
+        annotations: (c.annotations || []),
         getLabel: getLabel(c),
         getMetadata: getMetadata(c),
         getThumbnailURL: getThumbnailURL(c, images)
       } as CozyCanvas;
     });
+
+    const toRange = (source: Range): CozyRange => {
+      const items = source.items || [];
+
+      const nestedCanvases: CozyCanvas[] = items
+        .filter((item: any) => item.type === 'Canvas')
+        .map((item: any) => canvases.find(c => c.id === item.id)!)
+        .filter(Boolean);
+
+      const nestedRanges = items
+        .filter((item: any) => item.type === 'Range')
+        .map((item: any) => toRange(item));
+
+      const nestedItems = [...nestedCanvases, ...nestedRanges];
+        
+      return {
+        source,
+        id: source.id,
+        // Maintain original order
+        items: items.map((i: any) => nestedItems.find(cozy => cozy.id === i.id)),
+        canvases: nestedCanvases,
+        ranges: nestedRanges,
+        getLabel: getLabel(source)
+      } as CozyRange;
+    }
+
+    const ranges = sourceRanges.map((source: Range) => toRange(source));
+    return { canvases, ranges };
   }
 
   const v3: Manifest = majorVersion === 2 ? convertPresentation2(resource) : resource;
 
-  const canvases = parseV3(v3);
+  const { canvases, ranges } = parseV3(v3);
 
   return {
     source: v3,
     id: v3.id,
     majorVersion,
     canvases,
+    structure: ranges,
     getLabel: getLabel(v3),
-    getMetadata: getMetadata(v3)
+    getMetadata: getMetadata(v3),
+    getTableOfContents: getTableOfContents(ranges)
   }
 }
 
@@ -225,4 +259,6 @@ const parseImageResource = (resource: any) => {
       serviceUrl: normalizeServiceUrl(getPropertyValue<string>(resource, 'id'))
     } as ImageServiceResource;
   }
-}
+}
+
+export const Cozy = { parse, parseURL, Helpers };

package/src/core/index.ts

@@ -1,3 +1,4 @@
 export * from './canvas';
 export * from './image-service';
+export * from './manifest';
 export * from './resource';

package/src/core/manifest.ts

@@ -0,0 +1,38 @@
+import type { CozyRange, CozyTOCNode } from '../types';
+
+export const getTableOfContents = (ranges: CozyRange[]) => () => {
+
+  const buildTree = (range: CozyRange, parent: CozyTOCNode | undefined, level: number = 0): CozyTOCNode => {
+    const node: CozyTOCNode = {
+      id: range.id,
+      type: 'range',
+      getLabel: range.getLabel,
+      children: [],
+      parent,
+      level
+    };
+    
+    if (range.items && range.items.length > 0) {
+      range.items.forEach(item => {
+        if (item.source.type === 'Range') {
+          const childNode = buildTree(item as CozyRange, node, level + 1);
+          node.children.push(childNode);
+        } else {
+          node.children.push({
+            id: item.id,
+            type: 'canvas',
+            getLabel: item.getLabel,
+            children: [],
+            parent: node,
+            level: level + 1
+          });
+        }
+      });
+    }
+    
+    return node;
+  };
+
+  const topRanges = ranges.filter(range => range.source.behavior?.includes('top'));
+  return topRanges.map(range => buildTree(range, undefined));
+}

package/src/helpers/import-annotations.ts

@@ -0,0 +1,115 @@
+import { v4 as uuidv4 } from 'uuid';
+import type { Annotation } from '@iiif/presentation-3';
+import type { CozyCanvas, CozyManifest } from '../types';
+
+// Helper to escape special characters in strings used in RegExp
+const escapeRegExp = (str: string) =>
+  str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+const getAnnotationPageId = (canvas: CozyCanvas, namespace?: string) => {
+  if (namespace) {
+    // Use naming convention `{canvas.id}/namespace/page/p{idx}`. This means we need
+    // to find the highest index currently in use. (Index starts with 1.)
+    const pages = canvas.annotations;
+    if (pages.length > 0) {
+      const pattern = new RegExp(`${escapeRegExp(canvas.id)}/${escapeRegExp(namespace)}/page/p(\\d+)$`);
+      
+      const highestIdx = pages.reduce<number>((highest, page) => {
+        const match = page.id.match(pattern);
+        if (match && match[1]) {
+          const thisIndex = parseInt(match[1]);
+          return Math.max(highest, thisIndex);
+        } else {
+          return highest;
+        }
+      }, 1);
+
+      return `${canvas.id}/${namespace}/annotations/page/p${highestIdx}`;
+    } else {
+      return `${canvas.id}/${namespace}/annotations/page/p1`;
+    }
+  } else {
+    // Use UUIDs as a fallback naming convention
+    return `${canvas.id}/annotations/page/${uuidv4()}`;
+  }
+}
+
+/** 
+ * Will blindy attach the annotations to this canvas.
+ */
+const importAnnotationsToCanvas = (canvas: CozyCanvas, annotations: Annotation[], namespace?: string) => {
+  const page = {
+    id: getAnnotationPageId(canvas, namespace),
+    type: 'AnnotationPage',
+    items: annotations
+  }
+
+  return {
+    source: {
+      ...canvas.source,
+      annotations: [...canvas.annotations, page]
+    },
+    id: canvas.id,
+    width: canvas.width,
+    height: canvas.height,
+    images: [...canvas.images],
+    annotations: [...canvas.annotations, page],
+    getLabel: canvas.getLabel,
+    getMetadata: canvas.getMetadata,
+    getThumbnailURL: canvas.getThumbnailURL
+  } as CozyCanvas;
+}
+
+/**
+ * Will use 'source' information from the annotation targets to associate annotations with the right
+ * canvases.
+ */
+const importAnnotationsToManifest = (manifest: CozyManifest, annotations: Annotation[], namespace?: string) => {
+  const getSource = (annotation: Annotation) => {
+    const target = annotation.target;
+    if (!target) return;
+
+    if (typeof target === 'string')
+      return target.substring(0, target.indexOf('#'));
+    else
+      return (target as any).source; 
+  }
+
+  const bySource = annotations.reduce<Record<string, Annotation[]>>((acc, annotation) => {
+    const source = getSource(annotation);
+    if (!source) return acc;
+    
+    if (!acc[source]) acc[source] = [];
+    acc[source].push(annotation);
+
+    return acc;
+  }, {});
+
+  const canvases = manifest.canvases.map(canvas => {
+    const toImport = bySource[canvas.id] || [];
+    return toImport.length > 0 ? importAnnotationsToCanvas(canvas, toImport, namespace) : canvas;
+  });
+
+  return {
+    source: {
+      ...manifest.source,
+      items: canvases.map(c => c.source)
+    },
+    id: manifest.id,
+    majorVersion: manifest.majorVersion,
+    canvases,
+    structure: manifest.structure,
+    getLabel: manifest.getLabel,
+    getMetadata: manifest.getMetadata,
+    getTableOfContents: manifest.getTableOfContents
+  }
+}
+
+export const importAnnotations = <T extends CozyManifest | CozyCanvas>(
+  resource: T, 
+  annotations: Annotation[], 
+  namespace?: string
+): T extends CozyCanvas ? CozyCanvas : CozyManifest =>
+  resource.source.type === 'Canvas' 
+    ? importAnnotationsToCanvas(resource as CozyCanvas, annotations, namespace) as T extends CozyCanvas ? CozyCanvas : CozyManifest
+    : importAnnotationsToManifest(resource as CozyManifest, annotations, namespace) as T extends CozyCanvas ? CozyCanvas : CozyManifest;

package/src/helpers/index.ts

@@ -0,0 +1 @@
+export * from './import-annotations';

package/src/types.ts

@@ -1,4 +1,4 @@
-import type { Manifest, Canvas, ImageService2, ImageService3, IIIFExternalWebResource, Collection } from '@iiif/presentation-3';
+import type { Manifest, Canvas, ImageService2, ImageService3, IIIFExternalWebResource, Collection, Range, Annotation, AnnotationPage } from '@iiif/presentation-3';
 
 export type CozyParseResult = 
   | { type: 'collection', url: string, resource: CozyCollection }
@@ -50,12 +50,32 @@ export interface CozyManifest {
 
   readonly canvases: CozyCanvas[];
 
+  readonly structure: CozyRange[];
+
   getLabel(locale?: string): string | undefined;
 
+  getTableOfContents(): CozyTOCNode[];
+
   getMetadata(locale?: string): CozyMetadata[];
 
 }
 
+export interface CozyRange {
+
+  readonly source: Range;
+
+  readonly id: string;
+
+  readonly items: (CozyCanvas | CozyRange)[];
+
+  readonly canvases: CozyCanvas[];
+
+  readonly ranges: CozyRange[];
+
+  getLabel(locale?: string): string | undefined;
+
+}
+
 export interface CozyCanvas {
 
   readonly source: Canvas;
@@ -68,6 +88,8 @@ export interface CozyCanvas {
 
   readonly images: CozyImageResource[];
 
+  readonly annotations: AnnotationPage[];
+
   getLabel(locale?: string): string;
 
   getMetadata(locale?: string): CozyMetadata[];
@@ -84,6 +106,22 @@ export interface CozyMetadata {
 
 }
 
+export interface CozyTOCNode {
+
+  readonly id: string;
+
+  readonly type: 'range' | 'canvas';
+
+  getLabel(locale?: string): string | undefined;
+
+  children: CozyTOCNode[];
+
+  parent?: CozyTOCNode;
+
+  level: number;
+
+}
+
 export type CozyImageResource = 
   | StaticImageResource 
   | ImageServiceResource;

package/test/Cozy.test.ts

@@ -1,13 +1,27 @@
 import { describe, it, expect } from 'vitest';
-import { Cozy } from '../src';
+import { Cozy, CozyManifest } from '../src';
 
-import { COLLECTION } from './fixtures';
+import { COLLECTION, WITH_STRUCTURES } from './fixtures';
 
 describe('Cozy', () => {
 
   it('should parse collection manifests correctly', async () => {
-    const result = await Cozy.parseURL(COLLECTION)
+    const result = await Cozy.parseURL(COLLECTION);
     expect(result.type).toBe('collection');
-  })
+  });
+
+  it('should parse strctures in presentation manifests', async () => {
+    const result = await Cozy.parseURL(WITH_STRUCTURES);
+    expect(result.type).toBe('manifest');
+    expect('resource' in result).toBeTruthy();
+
+    const manifest = (result as any).resource as CozyManifest;
+    expect(manifest.structure.length > 0).toBeTruthy();
+
+    const tableOfContents = manifest.getTableOfContents();
+    expect(tableOfContents.length).toBe(1);
+    expect(tableOfContents[0].children.length).toBe(14);
+  });
 
 });
+