@widgetic/editor 4.0.9 → 4.0.11

package/README.md

@@ -38,6 +38,119 @@ dispatch('propertyChange', { schema, property, value});
 }} />
 ```
 
+## Using your own media library
+
+By default the file pickers inside the editor (the controls that open the File Browser) list and upload to the
+user's Widgetic uploads. A platform that keeps its media somewhere else passes a `mediaLibrary` and every picker uses
+it instead:
+
+```svelte
+<PropsEditor {designSchema} {contentSchema} mediaLibrary={myMediaLibrary} />
+```
+
+`mediaLibrary` is a `MediaLibraryProvider` (`list`, and optionally `upload`, `rename`, `delete`), exactly as the File
+Browser defines it: see "Using your own media library" in the
+[File Browser README](../file-browser/README.md). The value the editor reports for a picked file is `{ id, file, url }`
+(plus `hash` when the library gives one), taken from the library's file: `id` is the library's own id, `file` its
+name and `url` its address.
+
+With a library set, the pickers make no Widgetic upload request, not even when the page address carries `apiUrl` and
+`token`, and the File Browser keeps nothing on the device. Without one, nothing changes.
+
+Needs a `@widgetic/file-browser` that supports `mediaLibrary`; an older one ignores the prop and keeps using the
+Widgetic uploads.
+
+## Editing a whole composition
+
+`CompositionEditorApp` is the editor with everything around it. It loads one Widgetic composition, shows its settings
+(the `PropsEditor`) beside a live preview of the widget, and saves what the user changes. A page that has a token for
+the Widgetic API (a user's own, or an editor session token for a partner's managed user) only has to name the
+composition:
+
+```svelte
+<script>
+	import { CompositionEditorApp } from '@widgetic/editor';
+
+	// Called before every request, and again with 'expired' when the API refuses the token.
+	async function getAccessToken(reason) {
+		const response = await fetch('/my-backend/widgetic-editor-session', { method: 'POST' });
+		return (await response.json()).token;
+	}
+</script>
+
+<!-- It fills the box it is put in, so give the box a height. -->
+<div style="height: 100vh">
+	<CompositionEditorApp
+		compositionId="comp_123"
+		apiBasePath="https://api.widgetic.com/v1"
+		{getAccessToken}
+		on:saved={(event) => console.log('saved at', event.detail.savedAt)}
+	/>
+</div>
+```
+
+Props:
+
+- `compositionId`: the composition to edit. One component edits one composition: for another one, make another component.
+- `apiBasePath`: the API's address with its version (`https://api.widgetic.com/v1`). A blank one throws when the
+  component is made.
+- `getAccessToken`: `(reason: 'initial' | 'expired', refusedToken?: string) => string | Promise<string>`. See "The
+  token" below.
+- `mediaLibrary` (optional): the partner's own `MediaLibraryProvider` for the file pickers (see above). Without it the
+  pickers use the Widgetic library the token can see.
+- `googleFontsApiKey` (optional): the key the font pickers list Google Fonts with.
+- `autosaveDelayMs` (optional): how long to wait after the last change before saving by itself (default 2500); `0`
+  turns saving by itself off. Read once, when the component is made.
+- `class`, `style`: for the box the editor fills.
+
+**The token.** `getAccessToken` is called before every request, so a page that keeps its token fresh is always used
+up to date. When the API answers 401 the function is called again with `'expired'` and the token that was refused
+(`refusedToken`) and, only if the token that comes back is a different one, the request is sent once more (a save is
+sent with the same `Idempotency-Key` and body, so it cannot be applied twice). Several requests that start together with
+the same token are refused together, and each asks: if your function has already replaced `refusedToken`, hand out the
+new token instead of asking your server for another one. If the session is really over, the editor says so and `error`
+reports `failure.sessionEnded`.
+
+**Saving.** A change is saved a moment after the last one (2.5 seconds), or at once with the "Save" button. Only one
+save is on its way at a time, and a change made meanwhile is saved by the next one. A failure that may pass (no
+connection, a timeout, 429, 5xx) is tried again after 5, 15 and 45 seconds, the user can press "Try again" at any time,
+and a failure that cannot pass (the session ended, a refusal) is not retried.
+
+**The size.** The size the user gives the preview, by dragging its corner or typing it in, is saved with the composition
+(`embedSettings.width` and `height`) and is the size the widget gets where it is embedded. Nothing else changes it: the
+desktop and mobile buttons only change how the preview is looked at, and a box smaller than the preview shrinks it to
+fit without changing what is saved (so opening a composition in a small window does not edit it).
+
+Events (the data is in `event.detail`):
+
+- `ready` `{ name, widgetId }`: the editor is on the screen.
+- `dirty` `{ dirty }`: there is, or is no longer, work that is not saved.
+- `saved` `{ composition, savedAt }`: a save went through (`composition` is what the API answered).
+- `error` `{ during, failure, fatal }`: `during` is `'load'`, `'schemas'` or `'save'`; `failure` is
+  `{ message, code, status, retryable, sessionEnded, correlationId? }`; `fatal` is true when the composition could not
+  be loaded at all (the editor then shows its own message with "Try again").
+- `deviceView` `{ deviceView }`: the preview is looked at as `'desktop'` or `'mobile'` now, whether a button of the
+  preview, a size the user gave it or `setDeviceView()` did it. Told once per change.
+
+The component also has the methods `save()`, `flush()`, `isDirty()`, `getState()` and `reload()`. **Before removing
+the editor, `await flush()`**: removing it cancels whatever is on its way, and changes that were not saved are lost.
+
+For a page that has controls of its own around the editor:
+
+- `setDeviceView('desktop' | 'mobile')` does what the preview's desktop and mobile buttons do. It is a way of looking,
+  not an edit: nothing becomes unsaved.
+- `adoptEmbedSettings(settings)` is for a page that saves the composition's `embedSettings` itself (its own "Embed"
+  screen, say). The editor sends back the embed settings it loaded with every save, so without this a later save would put
+  them back. Call it after `await flush()` (so no save of the editor is on its way), with the settings the API now holds.
+  Nothing becomes unsaved, and the preview takes the size the settings name.
+
+What it asks of the API (all of it is on an editor session's allow-list): `GET /compositions/{id}`,
+`GET /compositions/{id}/preview`, `GET /compositions/{id}/schema/design`, `GET /compositions/{id}/schema/content` and
+`PUT /compositions/{id}`, plus `/uploads` for the default file library. A composition whose widget is not published
+has no preview address (`WIDGET_NOT_PUBLISHED`): its settings stay editable and the editor says why there is no preview.
+
+It is a Svelte component for a page that can import it, and it takes the page's styles and fonts as they are. A
+plain-JavaScript module that works on any page, inside a shadow root, is a separate step.
 
 ## Input Controllers
 
@@ -91,6 +204,11 @@ npm run dev
 npm run dev -- --open
 ```
 
+The dev server also serves three playground pages that need no sign-in:
+`/ic` (an input controller on its own), `/embed` (the Embed editor) and
+`/mock-widget`. They compile the sibling packages from source, so a change in
+`design-system` or `file-browser` shows up there without a build.
+
 ## Build the project
 
 To create a production version of your app:

package/dist/components/WidgetPreview.svelte

@@ -1,13 +1,16 @@
 <script lang="ts">
 	import { onMount, onDestroy, createEventDispatcher, tick } from 'svelte';
 	import { GenerateLoader } from '@widgetic/design-system/components';
+	import { lockPointerStyle } from '../utils/shadowDom';
 
 	const dispatch = createEventDispatcher<{
 		load: { src: string | null };
 		error: { src: string | null };
 		refresh: void;
 		openInTab: void;
-		resize: { width: number; height: number };
+		// `source` says where a size came from, so a host can tell a size the user chose ('drag', 'input', 'fit',
+		// 'device') from one the box around the preview forced on it ('clamp': the box is smaller than the size asked for).
+		resize: { width: number; height: number; source?: 'drag' | 'input' | 'fit' | 'device' | 'clamp' };
 		mobileViewport: { width: number; height: number };
 		desktopViewport: void;
 		deviceView: { mobile: boolean };
@@ -50,6 +53,17 @@
 	export let debugMode: boolean = false;
 	export let iframeReloadKey = 0;
 
+	// ── What the preview iframe may do ──────────────────────────────────────
+	/**
+	 * The iframe's `sandbox` tokens. `undefined` keeps what each mode always had (controlled: no sandbox; standalone:
+	 * scripts, popups, forms and its own origin); a string is used exactly as given; `null` means no `sandbox` at all.
+	 * A page that embeds the editor for its own visitors passes a list without `allow-top-navigation`, so that a
+	 * widget's code cannot send the visitor's whole tab somewhere else.
+	 */
+	export let sandbox: string | null | undefined = undefined;
+	/** The iframe's `allow` attribute: which of the page's permissions the preview may use. */
+	export let allow: string = 'clipboard-read; clipboard-write';
+
 	// ── Layout / chrome ─────────────────────────────────────────────────────
 	export let width: string = '100%';
 	export let height: string = '100%';
@@ -222,11 +236,19 @@
 			heightInputValue = String(Math.round(resizeHeight));
 		}
 		if (resizeWidth != null && resizeHeight != null) {
-			dispatch('resize', { width: resizeWidth, height: resizeHeight });
+			dispatch('resize', { width: resizeWidth, height: resizeHeight, source: 'input' });
 		}
 		console.log('[WidgetPreview] Dimension input', { dimension, value: parsed });
 	}
 
+	/**
+	 * While a drag or a resize lasts the pointer shows the matching cursor and nothing is selected as it moves
+	 * (`lockPointerStyle`, in `shadowDom.ts`: set on the host of the shadow root the editor lives in, or on <body> when
+	 * there is none, and put back afterwards). Puts back what the running drag or resize changed: the pointer style,
+	 * and the listeners on `document`.
+	 */
+	let finishPointerGesture: (() => void) | null = null;
+
 	function startPreviewDrag(event: PointerEvent) {
 		if (!enableDrag || isResizing) return;
 		const target = event.target as HTMLElement | null;
@@ -252,22 +274,25 @@
 
 		function endDrag() {
 			isDraggingPreview = false;
-			document.removeEventListener('pointermove', onPointerMove);
-			document.removeEventListener('pointerup', endDrag);
-			document.removeEventListener('pointercancel', endDrag);
-			document.body.style.removeProperty('user-select');
-			document.body.style.removeProperty('cursor');
+			finishPointerGesture?.();
 			console.log('[WidgetPreview] Preview drag end', {
 				left: previewShellLeft,
 				top: previewShellTop,
 			});
 		}
 
-		document.body.style.userSelect = 'none';
-		document.body.style.cursor = 'move';
+		finishPointerGesture?.();
+		const unlockPointerStyle = lockPointerStyle(event.target, 'move');
 		document.addEventListener('pointermove', onPointerMove);
 		document.addEventListener('pointerup', endDrag);
 		document.addEventListener('pointercancel', endDrag);
+		finishPointerGesture = () => {
+			document.removeEventListener('pointermove', onPointerMove);
+			document.removeEventListener('pointerup', endDrag);
+			document.removeEventListener('pointercancel', endDrag);
+			unlockPointerStyle();
+			finishPointerGesture = null;
+		};
 	}
 
 	/** Firefox/Chrome skip painting a cross-origin iframe that started at opacity 0 or inside a CSS filter until a reflow (opening DevTools). */
@@ -308,7 +333,7 @@
 			}
 			resizeWidth = limits.maxWidth;
 			resizeHeight = limits.maxHeight;
-			dispatch('resize', { width: limits.maxWidth, height: limits.maxHeight });
+			dispatch('resize', { width: limits.maxWidth, height: limits.maxHeight, source: 'fit' });
 			previewPositionReady = false;
 			requestAnimationFrame(() => {
 				resetPreviewPosition();
@@ -575,6 +600,9 @@
 	}
 
 	function handleMessage(event: MessageEvent) {
+		// Only the preview iframe of this component speaks to it: any other window on the page (a partner's own frames
+		// and scripts included) can post messages to this window too.
+		if (!iframeEl?.contentWindow || event.source !== iframeEl.contentWindow) return;
 		const type = event.data?.type;
 		if (type === 'widgetic:ready' || type === 'widgetic:pong') {
 			if (mode === 'standalone') {
@@ -597,7 +625,8 @@
 
 	function handleOpenInTabClick() {
 		const url = effectiveDisplayUrl || effectiveSrc;
-		if (url) window.open(url, '_blank');
+		// noopener: the page that opens must not get a handle on the page that opened it (which can be a partner's page).
+		if (url) window.open(url, '_blank', 'noopener,noreferrer');
 		dispatch('openInTab');
 	}
 
@@ -607,7 +636,7 @@
 		const h = Math.min(mobileViewportHeight, maxHeight);
 		resizeWidth = w;
 		resizeHeight = h;
-		dispatch('resize', { width: w, height: h });
+		dispatch('resize', { width: w, height: h, source: 'device' });
 		dispatch('mobileViewport', { width: w, height: h });
 	}
 
@@ -629,7 +658,7 @@
 		if (nextW !== resizeWidth || nextH !== resizeHeight) {
 			resizeWidth = nextW;
 			resizeHeight = nextH;
-			dispatch('resize', { width: nextW, height: nextH });
+			dispatch('resize', { width: nextW, height: nextH, source: 'clamp' });
 		}
 	}
 
@@ -689,35 +718,40 @@
 			}
 
 			if (resizeWidth != null && resizeHeight != null) {
-				dispatch('resize', { width: resizeWidth, height: resizeHeight });
+				dispatch('resize', { width: resizeWidth, height: resizeHeight, source: 'drag' });
 			}
 		}
 
 		function endResize() {
 			isResizing = false;
 			// Keep orange stroke while Alt remains held (composition corner mode).
-			document.removeEventListener('pointermove', onPointerMove);
-			document.removeEventListener('pointerup', endResize);
-			document.removeEventListener('pointercancel', endResize);
-			document.body.style.removeProperty('user-select');
-			document.body.style.removeProperty('cursor');
+			finishPointerGesture?.();
 			if (resizeWidth != null && resizeHeight != null) {
-				dispatch('resize', { width: resizeWidth, height: resizeHeight });
+				dispatch('resize', { width: resizeWidth, height: resizeHeight, source: 'drag' });
 			}
 		}
 
-		document.body.style.userSelect = 'none';
-		document.body.style.cursor =
+		finishPointerGesture?.();
+		const unlockPointerStyle = lockPointerStyle(
+			event.target,
 			signX !== 0 && signY !== 0
 				? signX * signY > 0
 					? 'nwse-resize'
 					: 'nesw-resize'
 				: signX !== 0
 					? 'ew-resize'
-					: 'ns-resize';
+					: 'ns-resize'
+		);
 		document.addEventListener('pointermove', onPointerMove);
 		document.addEventListener('pointerup', endResize);
 		document.addEventListener('pointercancel', endResize);
+		finishPointerGesture = () => {
+			document.removeEventListener('pointermove', onPointerMove);
+			document.removeEventListener('pointerup', endResize);
+			document.removeEventListener('pointercancel', endResize);
+			unlockPointerStyle();
+			finishPointerGesture = null;
+		};
 	}
 
 	$: if (enableResize && contentContainerEl && (resizeWidth != null || resizeHeight != null)) {
@@ -762,8 +796,8 @@
 	onDestroy(() => {
 		window.removeEventListener('message', handleMessage);
 		stageResizeObserver?.disconnect();
-		document.body.style.removeProperty('user-select');
-		document.body.style.removeProperty('cursor');
+		// A drag or resize that was still going when the editor was removed: stop listening and put the style back.
+		finishPointerGesture?.();
 	});
 </script>
 
@@ -1057,9 +1091,13 @@
 							src={mountedPreviewSrc}
 							class="widget-preview-iframe h-full w-full border-0"
 							tabindex="-1"
-							sandbox={mode === 'controlled' ? undefined : 'allow-scripts allow-popups allow-forms allow-same-origin'}
+							sandbox={sandbox !== undefined
+								? (sandbox ?? undefined)
+								: mode === 'controlled'
+									? undefined
+									: 'allow-scripts allow-popups allow-forms allow-same-origin'}
 							loading="eager"
-							allow="clipboard-read; clipboard-write"
+							{allow}
 							onload={handleIframeLoad}
 							onerror={handleIframeError}
 						></iframe>

package/dist/components/WidgetPreview.svelte.d.ts

@@ -34,6 +34,13 @@ declare const WidgetPreview: $$__sveltets_2_IsomorphicComponent<{
     forceMockReady?: boolean;
     debugMode?: boolean;
     iframeReloadKey?: number;
+    /**
+         * The iframe's `sandbox` tokens. `undefined` keeps what each mode always had (controlled: no sandbox; standalone:
+         * scripts, popups, forms and its own origin); a string is used exactly as given; `null` means no `sandbox` at all.
+         * A page that embeds the editor for its own visitors passes a list without `allow-top-navigation`, so that a
+         * widget's code cannot send the visitor's whole tab somewhere else.
+         */ sandbox?: string | null | undefined;
+    /** The iframe's `allow` attribute: which of the page's permissions the preview may use. */ allow?: string;
     width?: string;
     height?: string;
     contentHeight?: string;
@@ -82,6 +89,7 @@ declare const WidgetPreview: $$__sveltets_2_IsomorphicComponent<{
     resize: CustomEvent<{
         width: number;
         height: number;
+        source?: "drag" | "input" | "fit" | "device" | "clamp";
     }>;
     mobileViewport: CustomEvent<{
         width: number;