@bygga.dev/editor 0.1.0 → 0.3.0

package/README.md

@@ -0,0 +1,176 @@
+# @bygga.dev/editor
+
+`<bygga-editor>` — a visual builder for content **documents**, shipped as a native
+[custom element](https://developer.mozilla.org/en-US/docs/Web/API/Web_components).
+Email is the first document kind; landing pages are next. Built from Vue 3 and
+bundled with everything it needs, it embeds directly in any web page — no framework,
+no iframe — and renders into a shadow root, so host CSS can't leak in and editor
+styles can't leak out.
+
+## Install
+
+```sh
+npm install @bygga.dev/editor
+```
+
+The runtime bundle is self-contained — there are no peer dependencies to install
+(Vue is bundled in). Ships as ES modules with TypeScript declarations.
+
+## You need a licence key
+
+The editor **activates** before it mounts: on load it asks `https://api.bygga.dev` to attest the
+origin it is embedded on, and it renders only once it holds a signed attestation it can verify.
+Without a licence covering your domain it shows a short "Editor unavailable" panel instead.
+
+Your licence key goes in the `license-key` attribute. It is **public** — it lives in your page, it
+identifies which licence to check your domain against, and it proves nothing on its own, because the
+`Origin` header your browser sets is what actually gets attested. The same key authenticates
+compiling from your own backend, where there is no origin to attest — so treat it as public in a
+page and as a credential everywhere else.
+
+**`localhost` and `127.0.0.1` are licensed with no key at all**, so you can evaluate the editor with
+nothing to paste. Only deploying needs a licence.
+
+A licence covers a registrable domain and every subdomain of it, so one entry for `acme.com` covers
+`app.acme.com` and `staging.acme.com`. If your page sends a restrictive CSP, it needs
+`connect-src https://api.bygga.dev`.
+
+## Quick start
+
+Importing the package registers the `<bygga-editor>` element. Assign `config`
+(with a required `uploadImage`) **before** the element connects to the DOM, then give
+it a document:
+
+```js
+import '@bygga.dev/editor' // registers <bygga-editor>
+import { createEmptyDocument, parseDocument } from '@bygga.dev/editor'
+
+const editor = document.createElement('bygga-editor')
+
+// Your licence key. Omit it only on localhost, which is licensed without one.
+editor.setAttribute('license-key', 'bk_live_…')
+
+// Required. The editor calls this with an already-compressed image Blob and expects
+// a public, permanent, unauthenticated URL back — it goes straight into the document
+// JSON and, later, into a sent email.
+editor.config = {
+  async uploadImage(blob) {
+    return await uploadToYourStorage(blob)
+  },
+}
+
+editor.locale = 'en'
+editor.mergeTags = { firstName: { en: 'First name', sv: 'Förnamn' } }
+editor.document = createEmptyDocument() // or parseDocument(savedJson)
+
+editor.addEventListener('change', (event) => {
+  persist(event.detail[0]) // a detached JSON snapshot of the document
+})
+
+editor.style.height = '100vh' // it is display:block/height:100% — give it a sized container
+document.body.append(editor) // config is set, so it's safe to connect
+```
+
+## Host contract
+
+### `locale` attribute
+`sv` (default) or `en`. Reactive, and also sets the shadow tree's `lang` for
+assistive technology. Settable as the attribute or the `.locale` property.
+
+### `config` property *(required)*
+Host callbacks. Assign it **before** connecting the element (the editor throws at
+mount if `uploadImage` is missing):
+
+- **`uploadImage(blob: Blob): Promise<string>`** *(required)* — store the image and
+  resolve with a public URL. The Blob arrives already compressed and scaled, so don't
+  re-encode it; it may be called concurrently. The URL is written into the document
+  and then into sent email, so it must be absolute, unauthenticated, and permanent (a
+  presigned GET that expires will break in the inbox). Rejecting shows the user an
+  alert, keeps the block's previous image, and reports through `onImageError`.
+- **`saveDocument(document: Document): Promise<void>`** *(optional)* — push-save hook
+  invoked by `save()`; on success the editor marks the document saved. Rejecting
+  leaves the document dirty.
+- **`onImageError(error: unknown): void`** *(optional)* — called after the editor has
+  already told the user and recovered, for your own logging.
+
+### `document` property
+Assign a `Document` to load one; unset or `null` starts a blank document. It's a
+property, not an attribute — objects can't pass through an HTML attribute.
+
+### `mergeTags` property
+The personalization tags this host offers, keyed by the id the document stores, with
+per-locale labels (`{ firstName: { en: 'First name', sv: 'Förnamn' } }`). Populates
+the merge-tag picker; your backend must later resolve every id it sees. A missing
+locale label falls back to the default locale, then to the bare id.
+
+### `license-key` attribute
+Your licence key (see [You need a licence key](#you-need-a-licence-key)). Reactive: changing it
+re-activates, so a host that fetches its key can set it after the element is connected. Omit it on
+`localhost`, which is licensed without one.
+
+### Events
+- **`change`** — a `CustomEvent` fired whenever the document changes; `event.detail[0]`
+  is a detached JSON snapshot (persist it with `JSON.stringify`).
+- **`dirtychange`** — a `CustomEvent` fired when the unsaved-changes state flips;
+  `event.detail[0]` is a boolean. Drives, e.g., a Save button's enabled state.
+- **`licenseerror`** — a `CustomEvent` fired once when the editor refuses to open;
+  `event.detail[0]` is `{ reason }`, one of `key`, `domain`, `origin`, `malformed`,
+  `unreachable`, `invalid`, `insecure-context`. The panel and a fuller `console.error`
+  diagnostic are already handled — this is so you can route it into your own telemetry.
+  Events do not bubble, so listen on the element itself.
+
+### Methods
+- **`getDocument(): Document`** — the current document.
+- **`isDirty(): boolean`** — the current unsaved-changes state.
+- **`markSaved(): void`** — clear the unsaved-changes state after you persist.
+- **`save(): Promise<void>`** — routes through `config.saveDocument`, then marks
+  saved. Overlapping calls share one in-flight save.
+
+`getDocument()` throws and `save()` rejects while the editor is unlicensed, because there is no
+document behind them that anyone has edited — the editor never mounted. That matters if you autosave
+on a timer: without it, a licence outage would write a blank document over the stored one.
+
+Two ways to save: **pull** (`getDocument()`, persist it yourself, then `markSaved()`)
+or **push** (`save()`). `change` is a *notification*, not a request — a host that
+echoes every `change` payload back into the `document` property is declaring each
+keystroke saved and will never see the editor dirty.
+
+### The `Document`
+Opaque by design: persist it (it's plain JSON — `JSON.stringify` it) and hand it
+back, but don't reach into it, since the shape is the editor's to evolve. Two ways to
+get one:
+
+- **`createEmptyDocument()`** — a fresh blank document.
+- **`parseDocument(json)`** — the supported path from stored JSON back to a
+  `Document`. Throws if the editor can't open it, so a corrupt row fails at your load
+  boundary rather than deep inside the editor. Use what it returns, not what you
+  passed in.
+
+### Theming
+Design tokens are CSS custom properties (`--bygga-*`) read through the shadow boundary,
+so a host retheme is just setting them on the element:
+
+```css
+bygga-editor { --bygga-color-accent: #b00; }
+```
+
+## TypeScript
+
+The package augments `HTMLElementTagNameMap`, so
+`document.querySelector('bygga-editor')` is typed as `ByggaEditorElement` — its
+properties, methods, and a typed `addEventListener` for `change` / `dirtychange`
+included.
+
+- **Types:** `Document`, `EditorConfig`, `MergeTags`, `MergeTagLabels`, `Locale`,
+  `ByggaEditorElement`, `ByggaEditorEventMap`.
+- **Values:** `createEmptyDocument`, `parseDocument`, `SUPPORTED_LOCALES`,
+  `DEFAULT_LOCALE`, `EDITOR_TAG`, and `ByggaEditor` (the element constructor,
+  already registered on import).
+
+## Rendering to email
+
+The editor only edits and previews. Turning a saved document into sendable,
+email-client-safe HTML is done for you: the editor compiles while saving and hands it to
+`config.saveDocument(document, compiled)` as one standalone HTML string with `{{tag}}`
+placeholders. Substitute them with a find-and-replace at send time — escaping each value
+yourself, since they are spliced in raw.