@manifest-editor/shell 2.2.1-next.0.eefc2e3 → 2.2.2-next.0.4041094

package/README.md

@@ -1,278 +1,206 @@
-# Shell
+<p align="center">
+  <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>
+</p>
+<p align="center">
+  <a href="https://www.npmjs.com/package/@manifest-editor/shell"><img src="https://img.shields.io/npm/v/%40manifest-editor%2Fshell" alt="npm version"></a>
+  <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>
+  <a href="https://manifest-editor-docs.netlify.app/"><img src="https://img.shields.io/badge/docs-Manifest_Editor-blue" alt="Documentation"></a>
+</p>
 
+# @manifest-editor/shell
 
-## App context
+## Getting started with Manifest Editor
 
-### useApps()
+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.
 
-* Get current app
-* Change app
-* List all apps
+## About
 
-```js
-const { currentApp, apps, changeApp } = useApps();
+Application composition, state, layouts, plugins, configuration, and background tasks. Use this lower-level package when you need to assemble a custom editor beyond the combined component.
 
-// All app information.
-apps['manifest-editor'];
+## Quick start
 
-// Current app
-currentApp.id;
-
-// Change app
-changeApp({ id: 'manifest-editor' });
-
-// Change app with argument (launcher)
-changeApp({ id: 'collection-explorer', args: 'https://example.org/collection-123' });
+```sh
+npm install manifest-editor @manifest-editor/shell @manifest-editor/manifest-preset @iiif/helpers react-iiif-vault react@19 react-dom@19
 ```
 
-### useAppState()
-Global app state, currently only used for `canvasId`.
-* Get global state
-* Set global state
-
-```js
-const appState = useAppState();
-
-// Setting
-appState.setState({ canvasId: 'https://example.org/canvas-1' })
-
-// Getting
-appState.state.canvasId;
-
+```tsx
+import { AppProvider, Layout, PluginProvider, ShellProvider, mapApp } from "@manifest-editor/shell";
+import * as manifestPreset from "@manifest-editor/manifest-preset";
+import { VaultProvider } from "react-iiif-vault";
+import { Vault } from "@iiif/helpers";
+import "manifest-editor/index.css";
+
+const app = mapApp(manifestPreset);
+const vault = new Vault();
+const manifest = await vault.loadManifest("https://wellcomelibrary.org/iiif/b18035723/manifest");
+if (!manifest) throw new Error("Manifest could not be loaded");
+const resource = { id: manifest.id, type: "Manifest" as const };
+
+export function CustomEditor() {
+  return (
+    <PluginProvider plugins={manifestPreset.plugins}>
+      <AppProvider appId={app.metadata.id} definition={app} instanceId="my-editor">
+        <VaultProvider vault={vault}>
+          <ShellProvider resource={resource}>
+            <Layout />
+          </ShellProvider>
+        </VaultProvider>
+      </AppProvider>
+    </PluginProvider>
+  );
+}
 ```
 
-## Config context
+This browser-side example loads the manifest before mounting. Use a client-only entry point in applications with server rendering. The provider nesting is deliberate.
 
-```js
-const config = useConfig();
+## What the shell owns
 
+The shell connects a preset's UI definitions to a loaded IIIF resource. It owns panel state, editing selection, creator/editor dispatch, configuration, previews, plugins, and background work. It does not replace the Vault and does not itself implement a project-storage service.
 
-// Languages for the editor ['en, 'none']
-config.i18n.availableLanguages;
+| Layer | Responsibility |
+| --- | --- |
+| `PluginProvider` | Available plugin modules, enable/disable state, and global plugin settings. |
+| `AppProvider` | One mapped app definition, metadata, instance identity, and app-local state. |
+| `MultiAppProvider` | Optional app registry and switching; supplies the selected app through `AppProvider`. |
+| `VaultProvider` from `react-iiif-vault` | Loaded IIIF data and subscriptions. |
+| `ShellProvider` | The active root resource and the editing/layout/configuration contexts. |
+| `Layout` | Renders the selected panels and supporting UI. |
 
-// Behaviours string[]
-config.behaviorPresets;
+The quick start shows a single app. Keep providers and Vault instances stable when adding controls inside it. A hook that reads a provider's context must run below that provider.
 
-// IIIF collection for templates
-config.newTemplates;
+## Define or extend an app
 
-// List of previews.
-config.previews;
-```
+An app module supplies default metadata plus panel, editor, creator, and background definitions. `mapApp(module)` turns that into a `MappedApp` with `metadata`, `layout`, and optional configuration/preset data. Already mapped presets, such as `collectionPreset`, can be passed directly to `AppProvider`.
 
-## Layout
-* Get available layouts in app
-* Get layout state
-* Get layout actions
+`extendApp` is the composition helper used by the exhibition preset to reuse manifest editing while adding or replacing layout and configuration. The [exhibition preset source](../../presets/exhibition-preset/src/index.tsx) is a concrete example. Panel IDs are registration keys; actions must refer to an ID actually included in the active app.
 
+### A custom panel
 
-### Available layouts
-```js
-const layouts = useAvailableLayouts();
+```tsx
+import type { LayoutPanel } from "@manifest-editor/shell";
 
-// Loading status, check before listing.
-layouts.loading;
-
-// List of left panels.
-layouts.leftPanels;
-
-// List of center panels.
-layouts.centerPanels;
-
-// List of right panels
-layouts.rightPanels;
+export const notesPanel: LayoutPanel = {
+  id: "example-notes",
+  label: "Notes",
+  render: () => <p>Instructions for this editing workflow.</p>,
+};
 ```
 
-### Get layout state
-```js
-const {
-  leftPanel,
-  rightPanel,
-  pinnedRightPanel,
-  centerPanel,
-} = useLayoutState();
-
-// Following are the same for all.
+Add this definition to the app module's `leftPanels`, `rightPanels`, or `centerPanels` before mapping it. Defining a panel does not automatically select/open it.
 
-// Panel state (defined by app)
-leftPanel.state;
+## App selection and app-local state
 
-// Current identifier for panel
-leftPanel.current;
+`useApps()` requires `MultiAppProvider`. It returns `apps`, `currentApp`, `initialApp`, `changeApp`, and `changeProjectType`. `apps` is keyed by app ID; switching can carry arguments:
 
-// If the panel is open or not.
-leftPanel.open;
+```tsx
+import { useApps } from "@manifest-editor/shell";
 
-// If the panel is minimised (not yet implemented)
-leftPanel.minimised;
-
-// Custom width of panel, if set.
-leftPanel.customWidth;
-
-// Only for pinned:
+export function SwitchToManifestEditor() {
+  const { changeApp } = useApps();
+  return <button onClick={() => changeApp({ id: "manifest-editor" })}>Manifest editor</button>;
+}
+```
 
-// Can this be pinned;
-pinnedRightPanel.pinnable;
+`useApp()` reads the current mapped definition. `useAppInstance()` reads instance identity. `useAppState<T>()` exposes `state` and `setState` for application-local state; keep that separate from IIIF resource data in the Vault. The old `canvasId` example was an app convention, not the full scope of this store.
 
-// Is this pinned?
-pinnedRightPanel.pinned;
-```
+## Configuration
 
-### Get layout actions
-```js
-const actions = useLayoutActions();
+`useConfig()` exposes the merged editor configuration. `useSaveConfig()` supplies the persistence/update callback used by configuration controls. A host passes `config` and `saveConfig` into `ShellProvider` (or the combined `ManifestEditor`).
 
-// Open a panel
-actions.open('manifest-properties');
-actions.open('manifest-properties', { some: 'state' });
+Useful configuration areas include:
 
-// Change a panels state (does not open)
-actions.change('canvas-properties', { tab: 2 });
+| Key | Purpose |
+| --- | --- |
+| `i18n` | Default/available languages and advanced language editing. |
+| `editorConfig` | Per-resource editor settings, including hidden tabs. |
+| `editorFeatureFlags` | Canvas/media and interface options. |
+| `creators` | Configuration for individual creators. |
+| `previews`, `defaultPreview` | Available viewers and the preferred preview. |
+| `behaviorPresets`, `newTemplates` | Editing guidance and resource templates. |
+| `export` | Serialization version and identifier options. |
+| `plugins` | Per-editor plugin configuration. |
+| `urlState` | Host adapters for reading and replacing URL search parameters. |
 
-// Close panel
-actions.close('canvas-properties');
+The `Config` type is the authoritative list. It is separate from the lower-level `EditorConfig` in `@manifest-editor/editor-api`, which controls an individual editing operation.
 
-// Toggle panel
-actions.toggle('canvas-properties');
+## Layout state and actions
 
+`useAvailableLayouts()` returns panel definitions and optional loading state. `useLayoutState()` returns `leftPanel`, `centerPanel`, `rightPanel`, `pinnedRightPanel`, and `modal`. Each slot tracks `current`, `state`, `open`, `minimised`, `customWidth`, and a stack; the pinned slot also records pinning state.
 
-// Same actions as above are available PER panel
-actions.leftPanel;
-actions.rightPanel;
-actions.centerPanel;
+```tsx
+import { useLayoutActions, useLayoutState } from "@manifest-editor/shell";
 
-// And some additional on each:
-actions.leftPanel.resetSize();
-actions.leftPanel.setCustomWidth(450);
-actions.leftPanel.maximise(); // N/A
-actions.leftPanel.minimise(); // N/A
+export function PanelControls() {
+  const actions = useLayoutActions();
+  const { rightPanel } = useLayoutState();
+  return (
+    <button onClick={() => actions.rightPanel.close()} disabled={!rightPanel.open}>
+      Close inspector
+    </button>
+  );
+}
 ```
 
+Actions on registered panel IDs include `open(id, state?)`, `change(id, state?)`, `close(id)`, `toggle(id)`, and `stack(id, state?)`. Object overloads allow explicit stacking/state options. Per-slot actions such as `actions.leftPanel.open({ id, state })` use object arguments; they are not identical to the ID-based top-level helpers. Slots also expose resize, minimise/maximise, and stack navigation operations; the pinned slot adds `pin`/`unpin`.
 
-## Preview Context
-* Get selected preview
-* Get all activated previews
-* List all configurations and their class handlers
-* Activate, select and focus previews
-* Delete previews from storage
-* Update all existing previews (vault -> external)
-
-```js
-const preview = usePreviewContext();
+`actions.edit(reference, context?, options?)` routes a resource to the editor UI, with options for a property, selected tab, stacking, or forced opening. `actions.create(creatableResource)` opens the contextual creation workflow. Use `Creator.create()` from creator-api when you want headless execution instead of showing a picker/form.
 
-// Which preview is selected.
-preview.selected;
+## Editing selection and reusable controls
 
-// List of active preview ids
-preview.active;
+`useAppResource()` reads the root resource. The editing stack can point at a different resource, such as a Canvas or Annotation. `ResourceEditingProvider` supplies the reference for a reusable property control; `useResource<T>()` resolves it from the Vault and subscribes to changes:
 
-// List of all available preview configurations
-preview.configs;
+```tsx
+import type { DescriptiveProperties } from "@iiif/presentation-3";
+import { ResourceEditingProvider, useResource } from "@manifest-editor/shell";
 
-// List of all available config classes.
-preview.handlers;
+function ResourceIdentity() {
+  const resource = useResource<DescriptiveProperties>();
+  return <p>{resource.id}</p>;
+}
 
-// And actions
-preview.actions.activatePreview('universal-viewer');
-preview.actions.selectPreview('universal-viewer');
-preview.actions.deletePreview('universal-viewer');
-preview.actions.focusPreview('universal-viewer');
-preview.actions.updatePreviews();
+export function SelectedResource({ id }: { id: string }) {
+  return (
+    <ResourceEditingProvider resource={{ id, type: "Canvas" }}>
+      <ResourceIdentity />
+    </ResourceEditingProvider>
+  );
+}
 ```
 
-## Project context
-* Create project (then select automatically)
-* List all recent projects
-* Select a project to work on
+This example also needs a surrounding VaultProvider with the Canvas already loaded. `useResource` throws if nothing is selected. `useOptionalResource()` returns the optional **reference**, not a fully resolved entity. `useEditingResource` and `useEditingResourceStack` expose broader editing-navigation state.
 
+## Preview lifecycle
 
-### useProjectCreators()
-```js
-const { createProjectFromManifestId, createBlankManifest } = useProjectCreators();
+`usePreviewContext()` exposes `selected`, `active`, `configs`, `handlers`, and `actions`. A configuration selects a viewer; its handler implements creation, updates, focus, and deletion of preview instances.
 
-// Create and select a blank manifest
-await createBlankManifest();
+The actions are `activatePreview(id)`, `selectPreview(id)`, `focusPreview(id)`, `deletePreview(id)`, `updatePreviews()`, and `getPreviewLink()`. Use IDs from the configured previews rather than assuming a viewer is installed. Updating previews serializes or forwards the edited Vault state through the handler; it is not the same as saving the project.
 
-// Create a new project from external manifest id
-await createProjectFromManifestId('https://example.org/manifest');
-```
+For a live iframe, `createIframeVaultBridge(vault, port)` forwards host Vault state/actions over a MessagePort and returns cleanup. Its preview side is read-only: incoming mutation actions are rejected. `MessagePortClientVault` is re-exported for preview consumers. The host owns iframe creation, port transfer, and teardown.
 
-### useProjectContext()
-```js
-const ctx = useProjectContext();
-
-// Loading status (projects can be loaded from network)
-ctx.loadingStatus.loading;
-ctx.loadingStatus.loaded;
-ctx.loadingStatus.lastLoaded; // time.
-
-// Current proejct details (same for listing)
-ctx.current;
-ctx.current.name;
-ctx.current.thumbnail; // Optional
-ctx.current.previews; // list of previews
-ctx.current.resource.id; // Top level resource {id, type: Manifest}
-ctx.current.storage; // Configured storage for project
-ctx.current.settings; // Unused, future settings
-ctx.current.filename; // File name (unused)
-ctx.current.publications; // Future publish options
-ctx.current.metadata.modified; // Last modified
-ctx.current.metadata.created; // Created at
-
-// List of all projects
-ctx.allProjects;
-
-// Actions
-ctx.actions.switchProject('some-project-id');
-ctx.actions.createProject({ ... });
-ctx.actions.deselectProject('some-project-id')
-ctx.actions.saveProject({ ... });
-ctx.actions.updateThumbnail('...');
-ctx.actions.updateDetails({name: '..', filename: '..'});
-ctx.actions.updateSettings({ ... });
-
-// More internal actions
-ctx.actions.createPublication({ ... }); // unused
-ctx.actions.removePublication('publication-id');
-ctx.actions.updatePublication({ ... });
-ctx.actions.updateStorage({ ... });
-ctx.actions.setLoadingStatus({ ... })
-ctx.actions.load({ ...  });
-```
-
-## Resource editing context
+## Plugins, background work, and specifications
 
-Simple Context/hook combo
+Plugin modules contribute panels, editor/creator definitions, background tasks, settings, and metadata. Register the module namespace through `PluginProvider`; a metadata-only default export is not the complete plugin. `usePlugins`, `useEnabledPlugins`, and `usePluginActions` expose management state; `usePluginSettings` and `usePluginConfigApi` support plugin-specific preferences.
 
-Top level:
+Background actions are app/plugin contributions with their own execution and progress lifecycle. `useAvailableBackgroundActions()` groups the currently available actions; the supplied background action menu and toast components surface them. The specification context exposes configured rules and their reports for interfaces such as the Specifications plugin. These features belong in the shell because they coordinate UI, resource context, and longer-running work.
 
-```jsx
-const anno = { id: 'https://e.org/anno-1', type: 'Annotation' }
+## Projects are a separate package
 
-<ResourceEditingProvider resource={anno}>
-  <MyGenericEditor />
-</ResourceEditingProvider>
-```
+The previous shell README also documented project creation, recent projects, loading, storage, and saving. Those APIs now belong to [`@manifest-editor/projects`](../projects), not this package's exports. A multi-project host combines that package's `ProjectProvider` with `MultiAppProvider` and a Vault/storage backend. A single embedded editor does not need a project provider.
 
-And then inside the generic editor
+## Where to look next
 
-```typescript
-import {
-  DescriptiveProperties
-} from "@iiif/presentation-3";
+- [Layout contracts](./src/Layout/Layout.types.ts): panel definitions, action overloads, state, and render contexts.
+- [App composition](./src/AppContext): mapped apps, app state, and multi-app switching.
+- [Plugin contracts](./src/PluginContext/PluginContext.types.ts): modules, metadata, lazy loading, and settings.
+- [Configuration](./src/ConfigContext/ConfigContext.tsx): current configuration fields and defaults.
+- [Background tasks](./src/BackgroundTasks): action definitions and progress integration.
 
-function MyGenericEditor() {
+## API overview
 
-  // You can narrow with typescript
-  const resource = useResource<DescriptiveProperties>();
+- Composition: `mapApp`, `extendApp`, `AppProvider`, `PluginProvider`, `ShellProvider`, and `Layout`.
+- Layout definitions, panels, editing stacks, context menus, and resource hooks.
+- Plugin metadata, registration, settings, and enable/disable management.
+- Background actions, task progress, specifications, previews, and export controls.
+- `Config` and configuration providers for host-managed preferences.
 
-  // Although technical properties, the "ref" is always
-  // merged with the type.
-  resource.id
-  resource.type
-  resource.label
-  resource.summary
-  // ...
-
-}
-```
+See the [source exports](https://github.com/digirati-co-uk/iiif-manifest-editor/tree/main/packages/shell/src) for the complete API and TypeScript definitions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manifest-editor/shell",
-  "version": "2.2.1-next.0.eefc2e3",
+  "version": "2.2.2-next.0.4041094",
   "type": "module",
   "bugs": "https://github.com/digirati-co-uk/iiif-manifest-editor/issues",
   "repository": {
@@ -46,10 +46,10 @@
     "@iiif/parser": "4.0.1",
     "@iiif/presentation-3": "^2.2.3",
     "@iiif/presentation-3-normalized": "^0.9.7",
-    "@manifest-editor/client-vault": "2.2.1-next.0.eefc2e3",
-    "@manifest-editor/components": "2.2.1-next.0.eefc2e3",
-    "@manifest-editor/creator-api": "2.2.1-next.0.eefc2e3",
-    "@manifest-editor/editor-api": "2.2.1-next.0.eefc2e3",
+    "@manifest-editor/client-vault": "2.2.2-next.0.4041094",
+    "@manifest-editor/components": "2.2.2-next.0.4041094",
+    "@manifest-editor/creator-api": "2.2.2-next.0.4041094",
+    "@manifest-editor/editor-api": "2.2.2-next.0.4041094",
     "@react-stately/toast": "^3.1.2",
     "@tanstack/react-query": "^5.56.2",
     "immer": "^10.0.4",
@@ -70,7 +70,7 @@
     "zustand": "4.5.2"
   },
   "devDependencies": {
-    "@manifest-editor/ui": "2.2.0",
+    "@manifest-editor/ui": "2.2.1",
     "@tsdown/css": "0.22.14",
     "@types/react": "19.2.18",
     "@types/react-dom": "19.2.4",
@@ -84,7 +84,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "eefc2e321c6da5d194285621f4d26376088f2bb2",
+  "gitHead": "4041094cce4447f3aeb01fc7803322641b46c379",
   "inlinedDependencies": {
     "react-accessible-dropdown-menu-hook": "4.0.0",
     "tiny-invariant": "1.3.3"