@manifest-editor/creators 2.2.1-next.0.eefc2e3 → 2.2.2-next.0.903673e

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +91 -33
  2. package/package.json +8 -8
package/README.md CHANGED
@@ -1,49 +1,107 @@
1
- # Creators
1
+ <p align="center">
2
+ <a href="https://github.com/digirati-co-uk/iiif-manifest-editor"><img src="https://raw.githubusercontent.com/digirati-co-uk/iiif-manifest-editor/main/apps/docs/content/img/logo.svg" width="360" alt="Manifest Editor"></a>
3
+ </p>
4
+ <p align="center">
5
+ <a href="https://www.npmjs.com/package/@manifest-editor/creators"><img src="https://img.shields.io/npm/v/%40manifest-editor%2Fcreators" alt="npm version"></a>
6
+ <a href="https://github.com/digirati-co-uk/iiif-manifest-editor/actions/workflows/build-test.yml"><img src="https://img.shields.io/github/actions/workflow/status/digirati-co-uk/iiif-manifest-editor/build-test.yml?branch=main&amp;label=build" alt="Build status"></a>
7
+ <a href="https://manifest-editor-docs.netlify.app/"><img src="https://img.shields.io/badge/docs-Manifest_Editor-blue" alt="Documentation"></a>
8
+ </p>
2
9
 
3
- ## API Design
10
+ # @manifest-editor/creators
4
11
 
5
- The current API is a pain to use. Its lacking types.
12
+ ## Getting started with Manifest Editor
6
13
 
7
- Essentially this is the current creator hook/API (with no types!).
14
+ For the complete editor, start with [`manifest-editor`](https://www.npmjs.com/package/manifest-editor) and its [installation and integration guide](https://github.com/digirati-co-uk/iiif-manifest-editor/tree/main/packages/manifest-editor#readme). It combines the editor UI, presets, creators, and editing APIs. This package is one part of that workspace.
15
+
16
+ ## About
17
+
18
+ The built-in resource creation forms and functions: images, audio, video, HTML, canvases, annotations, ranges, and providers.
19
+
20
+ ## Quick start
21
+
22
+ ```sh
23
+ npm install @manifest-editor/creators
24
+ ```
8
25
 
9
26
  ```ts
10
- creator.create("@manifest-editor/image-url-creator", newThumbnail, {
11
- targetType: "ContentResource",
12
- parent: {
13
- property: "thumbnail",
14
- resource: {
15
- id: collection!.id,
16
- type: "Collection",
17
- },
18
- },
19
- initialData: {},
20
- });
27
+ import { allCreators, imageUrlCreator } from "@manifest-editor/creators";
28
+
29
+ // Use these definitions in a custom shell preset.
30
+ export const creators = allCreators;
31
+ export const imageOnlyCreators = [imageUrlCreator];
21
32
  ```
22
33
 
23
- Ideally something like this would work, and be type-safe.
34
+ The manifest preset already registers the standard creators. Use individual definitions when composing your own preset; render them through the shell creator UI.
24
35
 
25
- ```tsx
36
+ ## Choose a creator for the job
26
37
 
27
- const resource = { id: ..., type: 'Manifest' }; // Maybe from props or something.
28
- const createImage = useCreator(
29
- // Resource will have a type.
30
- resource,
31
- // This should be inferred from the resource type + supported fields.
32
- "thumbnail",
33
- // This should be inferred from the resource type + property supported type.
34
- "@manifest-editor/image-url-creator"
35
- );
38
+ A content resource and an annotation that paints it onto a Canvas are different things. Use a content-resource creator for a thumbnail, rendering, or body; use an annotation creator when you need a target, motivation, and body assembled together.
36
39
 
37
- // ...
38
- createImage({ url: 'https://example.org/image.jpg' });
39
- ```
40
+ | Task | Exported definitions |
41
+ | --- | --- |
42
+ | Image URL or IIIF Image API service | `imageUrlCreator`, `imageServiceCreator` |
43
+ | Paint images on a Canvas | `imageUrlAnnotation`, `imageServiceAnnotation`, `captionedImageAnnotation` |
44
+ | Multiple image URLs | `imageUrlListCreator`, `imageUrlListAnnotation` |
45
+ | Audio/video annotations | `audioAnnotation`, `videoAnnotation` |
46
+ | HTML, text links, web pages, YouTube | `htmlBodyCreator`, `htmlAnnotation`, `plaintextCreator`, `webPageCreator`, `youTubeBodyCreator` |
47
+ | Empty structure | `emptyCanvas`, `emptyAnnotationPage` |
48
+ | Ranges/table of contents | `rangeTopLevel`, `rangeWithItems` |
49
+ | Providers and manifests | `providerCreator`, `manifestBrowserCreator` |
50
+
51
+ Definitions carry their own `supports` rules. A creator appearing in this table does not mean it is valid for every parent property. Use each definition's `id` rather than guessing registration strings from its export name. `allCreators` is the standard list; it is not every exported definition (`manifestBrowserCreator`, for example, is deliberately separate).
40
52
 
41
- The same thing, but on the editor API.
53
+ ## Create a Canvas programmatically
42
54
 
43
55
  ```ts
44
- const manifestEditor = useManifestEditor();
56
+ import { Vault } from "@iiif/helpers";
57
+ import { Creator } from "@manifest-editor/creator-api";
58
+ import { emptyCanvas } from "@manifest-editor/creators";
45
59
 
46
- await manifestEditor.descriptive.thumbnail.create("@manifest-editor/image-url-creator", {
47
- url: "https://example.org/image.jpg",
60
+ const vault = new Vault();
61
+ const id = "https://example.org/manifest";
62
+ await vault.loadManifest(id, {
63
+ id, type: "Manifest", label: { en: ["My manifest"] }, items: [],
64
+ });
65
+ const creator = new Creator(vault, [emptyCanvas]);
66
+ await creator.create(emptyCanvas.id, {
67
+ label: { en: ["Page one"] }, width: 1200, height: 1800,
68
+ }, {
69
+ parent: { resource: { id, type: "Manifest" }, property: "items" },
48
70
  });
71
+ const json = vault.toPresentation3({ id, type: "Manifest" });
72
+ console.log(json);
49
73
  ```
74
+
75
+ Install `@manifest-editor/creator-api` and `@iiif/helpers` alongside this package for this example. `emptyCanvas` creates its empty AnnotationPage as well as the Canvas. The creator runtime imports both and adds the Canvas reference to the Manifest's `items`.
76
+
77
+ ## Register a smaller creation menu
78
+
79
+ A preset can export a curated `creators` array instead of `allCreators`. Include any definitions required by nested `ctx.create()` calls as well as the definitions you intend to show. Selection is contextual: supported parent fields/types and resource recognition determine which choices are offered.
80
+
81
+ For forms with a useful default, adapt a definition rather than forking its UI:
82
+
83
+ ```ts
84
+ import { withInitialData } from "@manifest-editor/creator-api";
85
+ import { imageUrlCreator } from "@manifest-editor/creators";
86
+
87
+ export const creators = [withInitialData(imageUrlCreator, {
88
+ url: "https://example.org/cover.jpg",
89
+ })];
90
+ ```
91
+
92
+ The prefilled URL is form initial data. A direct `Creator.create()` call still needs its own payload.
93
+
94
+ ## Reuse creation logic
95
+
96
+ Many definitions export their underlying creation functions and payload types, such as `createPlaintext` and `CreatePlaintextPayload`. Those functions take a payload **and** a `CreatorFunctionContext`; they are building blocks for another creator, not standalone Vault mutation functions. Use `Creator.create()` when you want the complete import/link/commit behavior.
97
+
98
+ See the [creator API guide](../creator-api) for custom definitions, nested creation, parent constraints, selectors, and the difference between render and execution contexts. Resource and annotation helpers may fetch external URLs; the host must allow those requests and handle failures from `create()`.
99
+
100
+ ## API overview
101
+
102
+ - `allCreators`: the standard creator definition list.
103
+ - Individual definitions such as `imageUrlCreator`, `imageServiceCreator`, `emptyCanvas`, `audioAnnotation`, `videoAnnotation`, `rangeTopLevel`, and `providerCreator`.
104
+ - Creation helpers exported alongside the definitions.
105
+ - `manifestBrowserCreator` is exported separately and is not included in `allCreators`.
106
+
107
+ See the [source exports](https://github.com/digirati-co-uk/iiif-manifest-editor/tree/main/packages/creators/src) for the complete API and TypeScript definitions.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@manifest-editor/creators",
3
- "version": "2.2.1-next.0.eefc2e3",
3
+ "version": "2.2.2-next.0.903673e",
4
4
  "type": "module",
5
5
  "bugs": "https://github.com/digirati-co-uk/iiif-manifest-editor/issues",
6
6
  "repository": {
@@ -43,11 +43,11 @@
43
43
  "@iiif/parser": "4.0.1",
44
44
  "@iiif/presentation-3": "^2.2.3",
45
45
  "@iiif/presentation-3-normalized": "^0.9.7",
46
- "@manifest-editor/components": "2.2.1-next.0.eefc2e3",
47
- "@manifest-editor/creator-api": "2.2.1-next.0.eefc2e3",
48
- "@manifest-editor/editor-api": "2.2.1-next.0.eefc2e3",
49
- "@manifest-editor/editors": "2.2.1-next.0.eefc2e3",
50
- "@manifest-editor/shell": "2.2.1-next.0.eefc2e3",
46
+ "@manifest-editor/components": "2.2.2-next.0.903673e",
47
+ "@manifest-editor/creator-api": "2.2.2-next.0.903673e",
48
+ "@manifest-editor/editor-api": "2.2.2-next.0.903673e",
49
+ "@manifest-editor/editors": "2.2.2-next.0.903673e",
50
+ "@manifest-editor/shell": "2.2.2-next.0.903673e",
51
51
  "iiif-browser": "https://pkg.pr.new/digirati-co-uk/iiif-browser/iiif-browser@4934ee2",
52
52
  "react": "19.2.8",
53
53
  "react-dom": "19.2.8",
@@ -57,7 +57,7 @@
57
57
  },
58
58
  "devDependencies": {
59
59
  "@atlas-viewer/iiif-image-api": "^2.2.0",
60
- "@manifest-editor/ui": "2.2.0",
60
+ "@manifest-editor/ui": "2.2.1",
61
61
  "@tsdown/css": "0.22.14",
62
62
  "@types/react": "19.2.18",
63
63
  "@types/react-dom": "19.2.4",
@@ -67,7 +67,7 @@
67
67
  "publishConfig": {
68
68
  "access": "public"
69
69
  },
70
- "gitHead": "eefc2e321c6da5d194285621f4d26376088f2bb2",
70
+ "gitHead": "903673e7c35feed673fc100cb0efe34733057c91",
71
71
  "inlinedDependencies": {
72
72
  "@atlas-viewer/iiif-image-api": "2.2.0",
73
73
  "tiny-invariant": "1.3.3"