@widgetic/editor 4.0.10 → 4.1.0

package/README.md

@@ -38,6 +38,243 @@ 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.
+
+## Languages
+
+The editor shows English until it is told otherwise. `CompositionEditorApp` takes two props, and both can change while
+the editor is open:
+
+```svelte
+<CompositionEditorApp
+	{compositionId}
+	{apiBasePath}
+	{getAccessToken}
+	locale="de"
+	messages={{
+		'editor.props.save': 'Speichern',
+		'editor.app.tryAgain': 'Erneut versuchen',
+		'action.cancel': 'Abbrechen',
+		'shadEditor.toolbar.bold': 'Fett (⌘B)'
+	}}
+/>
+```
+
+- **`locale`** is a BCP 47 language tag (`de`, `pt-BR`, `ar-EG`). It decides the plural rules and how numbers, dates and the
+  names of months and weekdays are written (all through `Intl`). It translates nothing. Blank or left out is English.
+- **`messages`** replaces words, and it is ONE flat object for everything inside the editor: the editor's own words
+  (keys that start with `editor.`), the File Browser that opens from its file pickers (`action.`, `upload.`, `dialog.` ...,
+  see the File Browser's README, "Languages") and the rich text editor of its text fields (`shadEditor.`). Give the keys
+  you want to change; every key you leave out stays English, so a language can be added one screen at a time. A key that
+  does not exist is ignored, and the console says `[Editor] ...` once, with the key you probably meant.
+
+`ALL_EDITOR_MESSAGES` is the list to hand to a translator: every key of the three catalogs with its English text.
+`EDITOR_MESSAGES` is the editor's own part of it.
+
+```ts
+import { ALL_EDITOR_MESSAGES, EDITOR_MESSAGES } from '@widgetic/editor';
+
+console.log(Object.keys(ALL_EDITOR_MESSAGES).length); // every word a person can read in the editor
+console.log(EDITOR_MESSAGES['editor.preview.compilationErrorsDetail']); // 'The generated code has syntax or compilation errors (HTTP {status}).'
+```
+
+A message is text. `{name}` puts a value in, and `{count, plural, one {# file} other {# files}}` picks a form for a
+number in the page's language (the format is the design system's: `@widgetic/design-system/i18n`). Each English message
+names the values it is given; a translation may leave one out or use them in any order, but it cannot ask for a value the
+message is never given.
+
+**Finding a mistake before a person does.** `checkEditorMessages(messages)` checks a `messages` object without showing
+anything: a key that does not exist (with the nearest real one), a value that is not text, a template that does not parse,
+a message that asks for a value it is never given. An empty list means every message will be used. Put it in a test of your
+page; `describeMessageProblem` (from `@widgetic/design-system/i18n`) turns each problem into a sentence:
+
+```ts
+import { checkEditorMessages } from '@widgetic/editor';
+import { describeMessageProblem } from '@widgetic/design-system/i18n';
+import german from './editor.de.json';
+
+expect(checkEditorMessages(german).map(describeMessageProblem)).toEqual([]);
+```
+
+While the editor runs, a message that cannot be used is never thrown: the English text of that key is shown.
+
+**Parts used on their own.** `PropsEditor`, `EmbedEditor` and `WidgetPreview` read their words from the language of the
+`CompositionEditorApp` they sit in. A page that mounts one of them without it says English, unless a component above it
+calls `provideEditorLanguage({ locale, messages })` while it is being made (it gives back a handle whose `update(...)`
+changes the language later). `useEditorLanguage()` is what the parts read it with.
+
+**What stays as it is**
+
+- **The widget's own words.** The names, descriptions and options of a widget's settings are written by the person who made
+  the widget, and are shown as written.
+- **What is saved with the composition.** The title of a new item ("Item 03"), "Untitled Composition" and the names a font
+  weight or a position is saved under ("ExtraBold", "top-left") are kept in English whatever the language. The editor shows
+  the weights, the tabs of the font and vector lists and the positions in the language; it saves the English name.
+- **What the editor tells the page's code.** `error` events, `failure.message` and the other event details stay English: they
+  are for your logs. The person is told by the editor's own screen, in the language.
+- **What comes from outside.** A sentence the Widgetic API sends back, or a media library you give the file pickers, is
+  shown as it arrived.
+- **A sentence the editor said once** (why there is no preview) keeps the language it was said in until the editor says
+  something new. Every label and button changes at once, and so do the banners of a composition that could not be loaded and
+  of a save that failed: they are written when they are drawn.
+- **Dates.** Months and weekdays follow `locale`, and so does the way the range control shows the chosen dates: 7 October 2026
+  is `10/07/26` with `en` (and with no `locale`), `07/10/26` with `en-GB` and `07.10.26` with `de`. In a language written right
+  to left a calendar writes each weekday in one letter (Arabic `ح ن ث ر خ ج س`) and gives a screen reader the whole name;
+  where the browser has no one-letter names (Urdu) the short names stay.
+- **Right to left.** The layout turns around when the editor is given `dir="rtl"` (see "Right to left" below). For a language written right to left a name that is put inside a sentence sits between two invisible marks (Unicode isolates U+2068 and U+2069, made by the shared translator), so the words around it cannot turn it around; a test that compares text has to leave them out.
+- **The design system.** The editor needs `@widgetic/design-system` **0.5.16 or newer** and a `@widgetic/file-browser` that
+  takes `locale` and `messages`: its words come from the design system's `@widgetic/design-system/i18n`.
+
+The `@widgetic/ui-sdk` module of the composition editor takes the same `locale` and `messages` and adds `setLanguage()`.
+
+### Right to left
+
+Arabic, Hebrew, Persian and Urdu start a line on the right. `CompositionEditorApp` takes one more prop for that, and it can
+change while the editor is open:
+
+```svelte
+<CompositionEditorApp {compositionId} {apiBasePath} {getAccessToken} locale="ar" messages={arabic} dir="rtl" />
+```
+
+- **`dir`** is `'rtl'` or `'ltr'`. It is not taken from `locale`: it says which way the screen is read, and a page decides
+  that (`resolveTextDirection(locale)` from `@widgetic/design-system/i18n` answers it for a language tag; the `@widgetic/ui-sdk`
+  module does exactly this). Left out, the editor follows the direction of the screen it sits in (a component above it that
+  calls `provideTextDirection(store)` from `@widgetic/design-system/components/textDirection`), and with neither it is left
+  to right, as it always was. The editor writes `dir` on its own root, so it is read the right way wherever it is put.
+- **What turns around.** The settings editor and the preview float over the editor's area and are put in place in pixels
+  when the editor appears and again when `dir` changes: on a right to left screen the settings editor is docked at the
+  right of the middle and the preview left of it, with the same gaps (`leftOnThisScreen`, `src/lib/utils/dockPlacement.ts`).
+  The Design and Content tabs, the label and the control of a row, the calendars (their arrows are mirrored), the sliders,
+  the switches and the file picker (the File Browser, which opens inside the editor's own root and is read the way the root
+  is) all start at the start of the line; the arrow keys of the date fields follow it, the help tip opens at the end of
+  the line, and each tab panel slides in from the side its tab is on.
+- **What a person types** is read by its own first letter on a right to left screen (`directionOfFieldValue`,
+  `src/lib/utils/fieldDirection.ts`): a sentence in Latin letters is set from the left and one in Arabic from the right,
+  in the same form. A field with nothing in it yet has no first letter (`dir="auto"` on an empty field reads left to right,
+  which would put the hint and the caret at the wrong edge), so it takes the direction of the screen. The kinds `email` and
+  `url` are addresses and stay left to right on every screen. Note that the kind a schema gives a plain text field is
+  `textInput`, not an HTML `type`: only those two names are addresses.
+- **Left to right on every screen.** The colour code, the drawing of the colour picker (saturation and hue), the grid that
+  places a box and the picker of the corners of a rounded box are drawings, not lines of text, and say `dir="ltr"` themselves.
+- **Keeping it so.** `tests/editor-placement.test.mjs` reads the source of the editor with `auditPhysicalPlacement` from
+  `@widgetic/design-system/rtl/audit` and fails on a class or a style that puts something on a physical side (`left`,
+  `right`, `ml-`, `pr-`, `text-left`, four-value shorthands such as `padding: 4px 6px 4px 0` ...): write `start`/`end`
+  (`ms-`, `pe-`, `text-start`, `border-s`) or say why with the note `rtl-ok` on the same line or the line above.
+  `tests/editor-direction.test.mjs` pins the rest. A panel that went off the screen in Arabic (a `position: relative` box
+  is moved from where it sits in the flow, which on a right to left screen is the right edge) and a field that never read
+  its text by its own letter were not found by the audit but by looking at a screen: look at one.
 
 ## Input Controllers
 
@@ -91,6 +328,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: