@widgetic/editor 4.0.11 → 4.1.2

package/README.md

@@ -152,6 +152,130 @@ has no preview address (`WIDGET_NOT_PUBLISHED`): its settings stay editable and
 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
 
 The component uses the input controllers to edit the widget properties.

package/dist/components/PreviewChromeControls.svelte

@@ -0,0 +1,84 @@
+<script lang="ts">
+	let className = '';
+	export { className as class };
+	export let style = '';
+	/** Desktop is the unpressed state of the phone icon. */
+	export let mobile = false;
+	export let showDevices = true;
+	export let showDimensions = true;
+	export let widthValue = '';
+	export let heightValue = '';
+	export let minWidth = 120;
+	export let minHeight = 80;
+	export let onDevice: (mobile: boolean) => void = () => {};
+	export let onWidth: (value: string) => void = () => {};
+	export let onHeight: (value: string) => void = () => {};
+	export let desktopLabel = 'Desktop preview';
+	export let mobileLabel = 'Mobile preview';
+	export let widthLabel = 'W';
+	export let heightLabel = 'H';
+</script>
+
+<div class="preview-chrome-controls flex items-center gap-2 {className}" style={style}>
+	{#if showDevices}
+		<div class="preview-chrome-device-toggle flex shrink-0 items-center overflow-hidden rounded border border-gray-300">
+			<button
+				type="button"
+				class="preview-chrome-device-desktop flex h-6 w-6 items-center justify-center {!mobile ? 'bg-gray-100 text-gray-800' : 'bg-white text-gray-400'} hover:text-gray-800 focus:outline-none focus-visible:outline-none"
+				aria-label={desktopLabel}
+				aria-pressed={!mobile}
+				onclick={() => onDevice(false)}
+				onpointerdown={(event) => event.stopPropagation()}
+			>
+				<svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="2" y="3" width="20" height="14" rx="2" ry="2"/><line x1="8" y1="21" x2="16" y2="21"/><line x1="12" y1="17" x2="12" y2="21"/></svg>
+			</button>
+			<button
+				type="button"
+				class="preview-chrome-device-mobile flex h-6 w-6 items-center justify-center border-s border-gray-300 {mobile ? 'bg-gray-100 text-gray-800' : 'bg-white text-gray-400'} hover:text-gray-800 focus:outline-none focus-visible:outline-none"
+				aria-label={mobileLabel}
+				aria-pressed={mobile}
+				onclick={() => onDevice(true)}
+				onpointerdown={(event) => event.stopPropagation()}
+			>
+				<svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="5" y="2" width="14" height="20" rx="2" ry="2"/><line x1="12" y1="18" x2="12.01" y2="18"/></svg>
+			</button>
+		</div>
+	{/if}
+	{#if showDimensions}
+		<div class="preview-chrome-dimensions flex items-center gap-1.5">
+			<label class="preview-dim-label flex items-center gap-1 text-[10px] font-semibold text-gray-500">
+				<span>{widthLabel}</span>
+				<input
+					type="number"
+					min={minWidth}
+					class="preview-dim-input w-14 h-6 rounded border border-gray-300 bg-white px-1 text-[11px] text-gray-800 focus:outline-none focus:border-blue-400 focus-visible:outline-none"
+					value={widthValue}
+					oninput={(event) => onWidth(event.currentTarget.value)}
+					onpointerdown={(event) => event.stopPropagation()}
+				/>
+			</label>
+			<span class="text-[10px] text-gray-400">×</span>
+			<label class="preview-dim-label flex items-center gap-1 text-[10px] font-semibold text-gray-500">
+				<span>{heightLabel}</span>
+				<input
+					type="number"
+					min={minHeight}
+					class="preview-dim-input w-14 h-6 rounded border border-gray-300 bg-white px-1 text-[11px] text-gray-800 focus:outline-none focus:border-blue-400 focus-visible:outline-none"
+					value={heightValue}
+					oninput={(event) => onHeight(event.currentTarget.value)}
+					onpointerdown={(event) => event.stopPropagation()}
+				/>
+			</label>
+		</div>
+	{/if}
+</div>
+
+<style>
+	.preview-chrome-controls button:focus,
+	.preview-chrome-controls button:focus-visible,
+	.preview-chrome-controls input:focus,
+	.preview-chrome-controls input:focus-visible {
+		outline: none;
+		box-shadow: none;
+	}
+</style>

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

@@ -0,0 +1,35 @@
+interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
+    new (options: import('svelte').ComponentConstructorOptions<Props>): import('svelte').SvelteComponent<Props, Events, Slots> & {
+        $$bindings?: Bindings;
+    } & Exports;
+    (internal: unknown, props: Props & {
+        $$events?: Events;
+        $$slots?: Slots;
+    }): Exports & {
+        $set?: any;
+        $on?: any;
+    };
+    z_$$bindings?: Bindings;
+}
+declare const PreviewChromeControls: $$__sveltets_2_IsomorphicComponent<{
+    class?: string;
+    style?: string;
+    /** Desktop is the unpressed state of the phone icon. */ mobile?: boolean;
+    showDevices?: boolean;
+    showDimensions?: boolean;
+    widthValue?: string;
+    heightValue?: string;
+    minWidth?: number;
+    minHeight?: number;
+    onDevice?: (mobile: boolean) => void;
+    onWidth?: (value: string) => void;
+    onHeight?: (value: string) => void;
+    desktopLabel?: string;
+    mobileLabel?: string;
+    widthLabel?: string;
+    heightLabel?: string;
+}, {
+    [evt: string]: CustomEvent<any>;
+}, {}, {}, string>;
+type PreviewChromeControls = InstanceType<typeof PreviewChromeControls>;
+export default PreviewChromeControls;