@manifest-editor/creator-api 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 digirati-co-uk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+# Creator API
+
+- What do you want to create
+  - The type + refined type
+  - The fields you add
+  - Static fields
+- Where is it valid to create
+  - Parent type
+  - Custom parent supports
+  - Parent fields
+- Canvas specific: how does it affect the canvas
+  - temporal
+  - spatial
+- What can it export as:
+  - Canvas
+  - Annotation
+  - Resource
+- Other
+  - Does it replace resources? (e.g. choice)
+  - Does it require canvas interaction
+
+Examples (cookbook)
+
+- Simple image
+- Simple audio
+- Simple video
+- Image with service
+- Cropped image (with service)
+- External HTML link
+- External PDF
+- External XML
+- External plaintext?
+- Commenting annotation on canvas
+- Tagging annotation at box
+- Creating range from canvas selection?
+- Creating choice from list of annotations
+
+The creation process is split into two parts:
+
+- The UI (e.g. the form that's presented to the user)
+- The building/creation process
+
+The creation process is intended to be dual purpose. This is not a great example, but here you can see that you can "call" other creators inside this creator. So they can become composable.
+
+```ts
+async function createThing(ctx) {
+  const image = await ctx.create("@manifest-editor/create-image", {
+    url: "https://example.org/image-1.jpg",
+  });
+
+  // If you want the underlying resource you just created.
+  const previewResource = image.get();
+
+  // Find a reference to an existing resource.
+  const ref = ctx.ref("https://example.org/canvas-1");
+
+  // Or you can create new resources that will be embedded.
+  const image2 = ctx.embed({
+    id: "https://example.org/image-2.jpg",
+    type: "Image",
+    height: 100,
+    width: 200,
+  });
+
+  // And then it can be part of a bigger resource:
+  // This cannot be a nested tree - it must be a flat resource with linked resources (like thumbnail) as
+  // objects like `ctx.create()` or `ctx.embed()`. This makes sure that we can piece together the finaly
+  // actions required in the last step.
+  return {
+    id: "https://example.org/image-3.jpg",
+    type: "Image",
+    height: ctx.data.height,
+    width: ctx.data.width,
+    thumbnail: [image],
+  };
+}
+```
+
+A "create" callback will be passed to the render, this is when this will be called and the resource will be created. Once created `edit()` will be called on the resource.

package/dist/index.cjs

@@ -0,0 +1,557 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var __publicField = (obj, key, value) => {
+  __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+  return value;
+};
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  Creator: () => Creator,
+  CreatorResource: () => CreatorResource
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/Creator.ts
+var import_vault = require("@iiif/helpers/vault");
+
+// src/CreatorRuntime.ts
+var import_actions = require("@iiif/helpers/vault/actions");
+
+// src/CreatorResource.ts
+var import_editor_api = require("@manifest-editor/editor-api");
+
+// src/ReferencedResource.ts
+var import_parser = require("@iiif/parser");
+var ReferencedResource = class {
+  constructor(reference, vault) {
+    __publicField(this, "vault");
+    __publicField(this, "original");
+    __publicField(this, "reference");
+    __publicField(this, "resource");
+    this.vault = vault;
+    this.original = reference;
+    this.reference = (0, import_parser.isSpecificResource)(reference) ? reference.source : reference;
+    this.resource = (0, import_parser.isSpecificResource)(reference) ? reference : { type: "SpecificResource", source: this.reference };
+  }
+  // @todo editable specific resource.
+  ref() {
+    return this.reference;
+  }
+  specificResource() {
+    return this.resource;
+  }
+  optionalSpecificResource() {
+    if ((0, import_parser.isSpecificResource)(this.original)) {
+      return {
+        ...this.original,
+        source: { id: this.original.source?.id, type: this.original.source?.type }
+      };
+    }
+    return this.original;
+  }
+  get() {
+    return this.vault.get(this.resource);
+  }
+};
+
+// src/utils.ts
+var import_parser2 = require("@iiif/parser");
+function resolveType(type) {
+  switch (type) {
+    case "Image":
+    case "Video":
+    case "Sound":
+    case "Dataset":
+    case "Text":
+    case "TextualBody":
+    case "Composite":
+    case "List":
+    case "Independents":
+    case "Audience":
+      return "ContentResource";
+    case "ImageService1":
+    case "ImageService2":
+    case "ImageService3":
+      return "Service";
+  }
+  return type;
+}
+var emptyTypes = {
+  Annotation: import_parser2.emptyAnnotation,
+  AnnotationPage: import_parser2.emptyAnnotationPage,
+  Canvas: import_parser2.emptyCanvas,
+  Collection: import_parser2.emptyCollection,
+  Manifest: import_parser2.emptyManifest,
+  Range: import_parser2.emptyRange,
+  ResourceProvider: import_parser2.emptyAgent,
+  Service: import_parser2.emptyService
+};
+function getEmptyType(type) {
+  const key = resolveType(type);
+  return emptyTypes[key] || {};
+}
+function randomId() {
+  return `${Math.random().toString(36).substr(2)}-${Date.now().toString(36)}`;
+}
+
+// src/CreatorResource.ts
+var import_parser3 = require("@iiif/parser");
+var CreatorResource = class _CreatorResource {
+  constructor(data, vault) {
+    __publicField(this, "resource");
+    __publicField(this, "warnings", []);
+    __publicField(this, "errors", []);
+    __publicField(this, "partOf");
+    __publicField(this, "references", []);
+    __publicField(this, "embedded", []);
+    __publicField(this, "vault");
+    __publicField(this, "specificResource");
+    this.vault = vault;
+    if (data.type === "SpecificResource") {
+      const source = data.source;
+      this.specificResource = { ...data, source: { id: source.id, type: resolveType(source.type) } };
+      data = source;
+    }
+    const properties = Object.keys(data);
+    const defaultType = getEmptyType(data.type);
+    for (const key of properties) {
+      if (import_editor_api.references.inlineProperties.includes(key) || !import_editor_api.references.all.includes(key)) {
+        continue;
+      }
+      if (data.type === "Range" && key === "items") {
+        const newRange = [];
+        for (const range of data[key]) {
+          if (range instanceof ReferencedResource) {
+            this.references.push(range);
+            newRange.push(range);
+            continue;
+          }
+          const rangeRef = new ReferencedResource(range, vault);
+          newRange.push(rangeRef);
+          data[key] = rangeRef;
+          continue;
+        }
+        data[key] = newRange;
+        continue;
+      }
+      if (data.type === "Manifest" && key === "start") {
+        const start = data[key];
+        if (start instanceof ReferencedResource) {
+          this.references.push(start);
+          continue;
+        }
+        const startRef = new ReferencedResource(start, vault);
+        data[key] = startRef;
+        continue;
+      }
+      if (data.type === "Annotation" && key === "target") {
+        let target = data[key];
+        if (target instanceof ReferencedResource) {
+          this.references.push(target);
+          continue;
+        }
+        if (typeof target === "string") {
+          target = { id: target, type: "Canvas" };
+        }
+        const targetRef = new ReferencedResource(target, vault);
+        data[key] = targetRef;
+        continue;
+      }
+      if (import_editor_api.references.single.includes(key)) {
+        continue;
+      }
+      if (import_editor_api.references.externalProperties.includes(key) || import_editor_api.references.internalProperties.includes(key)) {
+        const _items = data[key] || [];
+        const items = Array.isArray(_items) ? _items : [_items];
+        const newItems = [];
+        for (const item of items) {
+          if (item instanceof ReferencedResource) {
+            this.references.push(item);
+            newItems.push(item);
+            continue;
+          }
+          if (item instanceof _CreatorResource) {
+            this.embedded.push(item);
+            newItems.push(item);
+            continue;
+          }
+          const exists = this.vault.get(item, { skipSelfReturn: true });
+          if (exists) {
+            const type = resolveType(item.type);
+            const newItem = new ReferencedResource({ id: item.id, type }, vault);
+            this.references.push(newItem);
+            newItems.push(newItem);
+          } else {
+            const newItem = new _CreatorResource(item, vault);
+            this.embedded.push(newItem);
+            newItems.push(newItem);
+          }
+        }
+        data[key] = newItems;
+      }
+    }
+    this.resource = { ...defaultType, ...data };
+  }
+  // This is what is returned from the creator instance
+  get() {
+    return this.resource;
+  }
+  ref() {
+    if (this.specificResource) {
+      return this.specificResource;
+    }
+    return { id: this.resource.id, type: resolveType(this.resource.type) };
+  }
+  getAllReferencedResources() {
+    return this.references;
+  }
+  getAllEmbeddedResources() {
+    const allEmbedded = [];
+    for (const resource of this.embedded) {
+      allEmbedded.push(...resource.getAllEmbeddedResources());
+    }
+    allEmbedded.push(...this.embedded);
+    return allEmbedded;
+  }
+  getVaultResource() {
+    const resource = this.resource;
+    const properties = Object.keys(resource);
+    const newResource = {};
+    for (const key of properties) {
+      if (import_editor_api.references.inlineProperties.includes(key) || !import_editor_api.references.all.includes(key)) {
+        newResource[key] = resource[key];
+        continue;
+      }
+      if (import_editor_api.references.single.includes(key)) {
+        const ref = resource[key];
+        if (ref instanceof ReferencedResource) {
+          if (resource.type === "Manifest" && key === "start" || resource.type === "Annotation" && key === "target") {
+            newResource[key] = ref.specificResource();
+          } else {
+            newResource[key] = ref.optionalSpecificResource();
+          }
+        } else {
+          newResource[key] = resource[key];
+        }
+        continue;
+      }
+      if (resource[key]) {
+        newResource[key] = [];
+        for (const item of resource[key] || []) {
+          if (item instanceof ReferencedResource) {
+            newResource[key].push(item.optionalSpecificResource());
+          }
+          if (item instanceof _CreatorResource) {
+            newResource[key].push(item.ref());
+          }
+        }
+      }
+    }
+    if (this.partOf) {
+      newResource[import_parser3.HAS_PART] = newResource[import_parser3.HAS_PART] || [];
+      newResource[import_parser3.HAS_PART].push(this.partOf);
+    }
+    return newResource;
+  }
+  setPartOf(id) {
+    const ref = this.ref();
+    this.partOf = {
+      id: ref.id,
+      type: resolveType(ref.type),
+      [import_parser3.PART_OF]: id
+    };
+  }
+};
+
+// src/CreatorInstance.ts
+var CreatorInstance = class {
+  constructor(vault, options, createConfigs, previewVault) {
+    __publicField(this, "vault");
+    __publicField(this, "previewVault");
+    __publicField(this, "configs");
+    __publicField(this, "options");
+    this.vault = vault;
+    this.previewVault = previewVault;
+    this.options = options;
+    this.configs = createConfigs;
+  }
+  getPreviewVault() {
+    return this.previewVault;
+  }
+  getTarget() {
+    const target = this.options.target || this.options.parent?.resource;
+    const position = this.options.initialData?.selector;
+    if (position && position.type === "polygon") {
+      const position2 = this.options.initialData?.selector;
+      const { width, height } = this.options.initialData?.on || {};
+      if (position2.shape.points.length === 0) {
+        return target;
+      }
+      if (position2.shape.points.length === 1) {
+        const points = position2.shape.points[0];
+        return {
+          type: "SpecificResource",
+          source: target,
+          selector: {
+            type: "PointSelector",
+            x: points[0],
+            y: points[1]
+          }
+        };
+      }
+      if (position2.shape.points.length === 4) {
+        const [topLeft, topRight, bottomRight, bottomLeft] = position2.shape.points;
+        if (topLeft[0] === topRight[0] && topLeft[1] === bottomLeft[1] && topRight[1] === bottomRight[1] && bottomLeft[0] === bottomRight[0]) {
+          const x = Math.min(topLeft[0], topRight[0], bottomRight[0], bottomLeft[0]);
+          const y = Math.min(topLeft[1], topRight[1], bottomRight[1], bottomLeft[1]);
+          const x2 = Math.max(topLeft[0], topRight[0], bottomRight[0], bottomLeft[0]);
+          const y2 = Math.max(topLeft[1], topRight[1], bottomRight[1], bottomLeft[1]);
+          const width2 = x2 - x;
+          const height2 = y2 - y;
+          return {
+            type: "SpecificResource",
+            source: target,
+            selector: {
+              type: "FragmentSelector",
+              value: `xywh=${[~~x, ~~y, ~~width2, ~~height2].join(",")}`
+            }
+          };
+        }
+      }
+      const el = position2.shape.open ? "polyline" : "polygon";
+      return {
+        type: "SpecificResource",
+        source: target,
+        selector: {
+          type: "SvgSelector",
+          value: `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${width} ${height}" width="${width}" height="${height}"><${el} points="${position2.shape.points.map((p) => p.join(",")).join(" ")}" /></svg>`
+        }
+      };
+    }
+    if (target && position) {
+      return {
+        type: "SpecificResource",
+        source: target,
+        selector: {
+          type: "FragmentSelector",
+          value: `xywh=${[~~position.x, ~~position.y, ~~position.width, ~~position.height].join(",")}`
+        }
+      };
+    }
+    return target;
+  }
+  getParent() {
+    return this.options.parent?.resource;
+  }
+  getParentResource() {
+    const parent = this.getParent();
+    if (parent) {
+      return {
+        type: "SpecificResource",
+        source: parent
+      };
+    }
+  }
+  generateId(type, parent) {
+    if (parent && parent instanceof ReferencedResource) {
+      parent = parent.ref();
+    }
+    return `${(parent || this.options.parent?.resource)?.id}/${type}/${randomId()}`;
+  }
+  ref(idOrRef) {
+    let id = "";
+    let type = "";
+    if (typeof idOrRef === "string") {
+      id = idOrRef;
+    } else {
+      id = idOrRef.id;
+      type = idOrRef.type;
+    }
+    const state = this.vault.getState();
+    const realType = state.iiif.mapping[id];
+    if (!realType) {
+      type = type || "unknown";
+    } else {
+      type = realType;
+    }
+    return new ReferencedResource({ id, type }, this.vault);
+  }
+  embed(data) {
+    return new CreatorResource(data, this.vault);
+  }
+  async create(definition, payload, options) {
+    const foundDefinition = this.configs.find((t) => t.id === definition);
+    if (!foundDefinition) {
+      throw new Error(`Creator config ${definition} not found`);
+    }
+    const runtime = new CreatorRuntime(this.vault, foundDefinition, payload, this.configs, this.previewVault, options);
+    return await runtime.run();
+  }
+};
+
+// src/CreatorRuntime.ts
+var CreatorRuntime = class {
+  constructor(vault, definition, payload, createConfigs, previewVault, options) {
+    // This will hold state for the creation process
+    __publicField(this, "resource", null);
+    __publicField(this, "payload");
+    __publicField(this, "vault");
+    __publicField(this, "previewVault");
+    __publicField(this, "definition");
+    __publicField(this, "options");
+    __publicField(this, "configs");
+    this.vault = vault;
+    this.previewVault = previewVault;
+    this.definition = definition;
+    this.payload = payload;
+    this.configs = createConfigs;
+    this.options = {
+      targetType: (options || {}).targetType || definition.resourceType,
+      ...options || {}
+    };
+  }
+  async run() {
+    const instance = new CreatorInstance(this.vault, this.options, this.configs, this.previewVault);
+    const result = await this.definition.create(this.payload, instance);
+    if (result instanceof CreatorResource) {
+      this.resource = result;
+    } else {
+      this.resource = new CreatorResource(result, this.vault);
+    }
+    return this.resource;
+  }
+  getActions() {
+    if (!this.resource) {
+      return [];
+    }
+    const actions = [];
+    const resources = {};
+    const mapping = {};
+    if (this.options.parent) {
+      this.resource.setPartOf(this.options.parent.resource.id);
+    }
+    const embedded = this.resource.getAllEmbeddedResources();
+    const allItems = [...embedded, this.resource];
+    for (const item of allItems) {
+      const resource = item.getVaultResource();
+      if (!resource.type || !resource.id) {
+        continue;
+      }
+      const type = resolveType(resource.type);
+      resources[type] = resources[type] ? resources[type] : {};
+      resources[type][resource.id] = resource;
+      mapping[resource.id] = type;
+    }
+    actions.push((0, import_actions.importEntities)({ entities: resources }));
+    actions.push((0, import_actions.addMappings)({ mapping }));
+    return actions;
+  }
+  commit(afterActions = []) {
+    if (!this.resource) {
+      throw new Error("Creator has not been run");
+    }
+    const actions = this.getActions();
+    this.vault.dispatch((0, import_actions.batchActions)({ actions: [...actions, ...afterActions] }));
+    return this.resource.ref();
+  }
+};
+
+// src/Creator.ts
+var import_actions2 = require("@iiif/helpers/vault/actions");
+var Creator = class {
+  constructor(vault, configs, previewVault) {
+    __publicField(this, "configs");
+    __publicField(this, "vault");
+    __publicField(this, "previewVault");
+    this.configs = configs || [];
+    this.vault = vault;
+    this.previewVault = previewVault || new import_vault.Vault();
+  }
+  async create(definition, payload, options) {
+    const foundDefinition = this.configs.find((t) => t.id === definition);
+    if (!foundDefinition) {
+      throw new Error(`Creator config ${definition} not found`);
+    }
+    if (options?.parent) {
+      if (foundDefinition.supports.parentTypes) {
+        if (!foundDefinition.supports.parentTypes.includes(options.parent.resource.type)) {
+          throw new Error(`Definition ${definition} does not support parent type ${options.parent.resource.type}`);
+        }
+      }
+      if (foundDefinition.supports.parentFields) {
+        if (!foundDefinition.supports.parentFields.includes(options.parent.property)) {
+          throw new Error(`Definition ${definition} does not support parent field ${options.parent.property}`);
+        }
+      }
+      if (foundDefinition.supports.parentFieldMap) {
+        const type = foundDefinition.supports.parentFieldMap[options.parent.resource.type];
+        if (!type || !type.includes(options.parent.property)) {
+          throw new Error(
+            `Definition ${definition} does not support parent ${options.parent.property} / ${options.parent.property}`
+          );
+        }
+      }
+      if (foundDefinition.supports.custom) {
+        const isValid = foundDefinition.supports.custom(options.parent, this.vault);
+        if (!isValid) {
+          throw new Error(`Definition does not support resource`);
+        }
+      }
+    }
+    const runtime = new CreatorRuntime(this.vault, foundDefinition, payload, this.configs, this.previewVault, options);
+    const resource = await runtime.run();
+    const afterActions = [];
+    if (options?.parent) {
+      if (options.parent.property === "start" || options.parent.property === "target") {
+        afterActions.push(
+          import_actions2.entityActions.modifyEntityField({
+            id: options.parent.resource.id,
+            type: options.parent.resource.type,
+            value: resource.ref(),
+            key: options.parent.property
+          })
+        );
+      } else {
+        afterActions.push(
+          import_actions2.entityActions.addReference({
+            id: options.parent.resource.id,
+            type: options.parent.resource.type,
+            reference: resource.ref(),
+            key: options.parent.property,
+            index: options.parent.atIndex
+          })
+        );
+      }
+    }
+    const result = runtime.commit(afterActions);
+    if (options?.parent) {
+      if (foundDefinition.sideEffects) {
+        for (const sideEffect of foundDefinition.sideEffects) {
+          if (sideEffect.run) {
+            await sideEffect.run(result, { vault: this.vault, options });
+          }
+        }
+      }
+    }
+    return result;
+  }
+};