@weavour/editor 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Weavour contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,114 @@
-# Temporary Holding Version
+# Weavour editor SDKs
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Embed the hosted Weavour email editor in your application. Your application owns
+its users and sends the exported emails. The SDKs are MIT licensed; the hosted
+editor, rendering implementation and services are proprietary.
+
+- `@weavour/editor`: JavaScript/TypeScript and classic script-tag integrations.
+- `@weavour/react`: React component using the same core and hosted iframe.
+
+## JavaScript / TypeScript
+
+```sh
+npm install @weavour/editor
+```
+
+```ts
+import { mount } from '@weavour/editor';
+
+const editor = mount('#email-editor', {
+  editorKey: 'YOUR_PUBLIC_EDITOR_KEY',
+  userId: 'user-123',
+  organizationId: 'organization-456',
+  locale: 'en',
+  onDocumentChange(email) { /* Persist the complete versioned envelope. */ },
+  onError(error) { console.error(error); },
+});
+await editor.ready;
+const { html, text, subject, preheader } = await editor.exportHTML();
+// Your application sends the email.
+// Before leaving, optionally await editor.flushAutosave(), then:
+editor.destroy();
+```
+
+Supply an element with an explicit height, for example 700px. The SDK appends a
+full-width, full-height titled iframe and preserves other container children.
+The default iframe is `https://weavour.com/editor`. Local integration can set
+`editorUrl: 'http://localhost:8788/editor'` and
+`apiUrl: 'http://localhost:8787'` explicitly.
+
+## Script tags
+
+Use the `dist/editor.js` artifact from a pinned SDK release. It exposes the same
+API as `Weavour.mount(...)`; no framework or npm runtime is required.
+`https://weavour.com/editor.js` remains the hosted compatibility entry point.
+The new application-ready SDK requires the matching hosted iframe rollout;
+see [compatibility](docs/compatibility.md) before switching production clients.
+
+## React
+
+```sh
+npm install @weavour/react
+```
+
+```tsx
+import { useRef } from 'react';
+import { WeavourEditor, type WeavourEditorRef } from '@weavour/react';
+
+export function EmailComposer() {
+  const editor = useRef<WeavourEditorRef>(null);
+  return <WeavourEditor
+    ref={editor}
+    editorKey="YOUR_PUBLIC_EDITOR_KEY"
+    userId="user-123"
+    organizationId="organization-456"
+    locale="en"
+    style={{ height: 700 }}
+    onError={console.error}
+  />;
+}
+```
+
+The wrapper cleans up on unmount and supports React 18.3 and 19. Theme, locale,
+merge tags and feature preferences update live. Change the React `key` explicitly
+to switch identity or initial documents, after preserving current work. Callback
+changes do not recreate the iframe. Imports are SSR-safe; mounting runs on the
+client. Next.js examples use a client component boundary.
+
+## Identity and permissions
+
+`editorKey` is public. `userId` and optional `organizationId` are declarative
+namespaces inside the customer workspace resolved by that key. They are not
+verified identities: supplying the same IDs grants shared access, including
+modification. Origin restrictions control embedding and do not authenticate users.
+An organization-only mount becomes a personal mount with that organization ID as
+its user ID. A mount with neither ID fails. Never put admin credentials or AI
+provider keys in mount options. Hosted capabilities and quotas are enforced by
+the service, regardless of local preferences.
+
+## Documentation and examples
+
+- [API](docs/api.md), [compatibility and migration](docs/compatibility.md),
+  [origins and CSP](docs/security.md).
+- [Vanilla](examples/vanilla), [React](examples/react), [Next.js](examples/next).
+- [Contributing](CONTRIBUTING.md), [security reports](SECURITY.md), [changelog](CHANGELOG.md).
+
+## Development
+
+Node.js 22.12+ and npm are required. A clean public checkout needs no credentials,
+private code or Weavour account to build and test:
+
+```sh
+npm ci
+npm run verify
+npx playwright install chromium firefox webkit
+npm run test:browser
+```
+
+GitHub Actions runs package checks and tests on **every push and pull request**,
+using Node 22/24 and React 18/19, plus Chromium, Firefox and WebKit browser checks.
+Browser tests use a small mock iframe, not a copy of the hosted editor. Real
+hosted integrations require a configured public editor key and allowed origin.
+
+See [release instructions](docs/releases.md) for npm trusted publishing and
+private hosted-editor promotion. Installing this SDK does not self-host the editor.

package/dist/classic.d.ts

@@ -0,0 +1,6 @@
+import type { EditorSDK } from './types.js';
+declare global {
+    interface Window {
+        Weavour?: EditorSDK;
+    }
+}

package/dist/core.d.ts

@@ -0,0 +1,2 @@
+import type { EditorSDK, SDKOptions } from './types.js';
+export declare function createSDK(settings?: SDKOptions): EditorSDK;

package/dist/editor-blocks.d.ts

@@ -0,0 +1,2 @@
+export declare const editorBlockIds: readonly ["text", "heading", "button", "image", "video", "gif", "timer", "menu", "social", "unsubscribe", "list", "html", "space", "divider", "section", "columns"];
+export type EditorBlockId = typeof editorBlockIds[number];

package/dist/editor-theme.d.ts

@@ -0,0 +1,30 @@
+export type EditorTheme = {
+    mode?: 'light' | 'dark';
+    primaryColor?: string;
+    backgroundColor?: string;
+    surfaceColor?: string;
+    shellColor?: string;
+    inputColor?: string;
+    textColor?: string;
+    mutedColor?: string;
+    borderColor?: string;
+    cornerRadius?: number;
+    density?: 'comfortable' | 'compact';
+    fontFamily?: string;
+};
+export declare function resolveEditorTheme(input?: EditorTheme): Required<EditorTheme>;
+export declare function colorContrast(first: string, second: string): number;
+export declare function readableForeground(background: string): "#ffffff" | "#111111" | "#000000";
+export declare function editorSurfacePalette(background: string, theme: EditorTheme): {
+    text: string;
+    muted: string;
+    danger: string;
+    focus: string;
+    hover: string;
+    selected: string;
+    accessory: string;
+    accessoryText: string;
+    accessoryFocus: string;
+    border: string;
+    colorScheme: string;
+};