@picsart/react-photo-editor 1.0.0 → 1.0.2

package/README.md

@@ -1,6 +1,6 @@
 # @picsart/react-photo-editor
 
-React component for embedding the Picsart Photo & Video Editor (Create) SDK in web apps.
+React component that loads the **official Picsart Create SDK** from `sdk.picsart.io` (script tag) and mounts the editor into your page. No bundled copy of the editor runtime is shipped in this package—only a thin React wrapper.
 
 ## Install
 
@@ -8,51 +8,60 @@ React component for embedding the Picsart Photo & Video Editor (Create) SDK in w
 npm install @picsart/react-photo-editor
 ```
 
-Requires **React 17+** as a peer dependency.
+Peer dependencies: **React 17+** and **react-dom**.
 
 ## Usage
 
+Callers must set the same core fields as the [Picsart quick start](https://docs.picsart.io/docs/photo-video-editor-quick-start): **`apiKey`**, **`customerId`**, **`propertyId`**. The component renders the editor container and passes a matching **`containerId`** to the SDK (you can set **`containerId`** yourself, or omit it to get a stable auto-generated id). **`title`** defaults to **`Photo Print Designer`** if omitted.
+
 ```tsx
-import { PhotoEditor } from '@picsart/react-photo-editor';
+import { PicsartEditor } from '@picsart/react-photo-editor';
 
-export function Editor() {
+export function Page() {
   return (
-    <PhotoEditor
+    <PicsartEditor
       apiKey={process.env.NEXT_PUBLIC_PICSART_API_KEY!}
       customerId={process.env.NEXT_PUBLIC_PICSART_CUSTOMER_ID!}
-      propertyId={process.env.NEXT_PUBLIC_PICSART_PROPERTY_ID}
-      editorDomain={process.env.NEXT_PUBLIC_PICSART_EDITOR_DOMAIN!}
-      parentDomain={process.env.NEXT_PUBLIC_PICSART_PARENT_DOMAIN}
-      imageUrl="https://example.com/image.png"
-      onExport={(result) => console.log(result)}
+      propertyId={process.env.NEXT_PUBLIC_PICSART_PROPERTY_ID!}
+      containerId="my-editor-root"
+      title="Photo Print Designer"
     />
   );
 }
 ```
 
-For local dev over `http://localhost`, set **`parentDomain`** (or `NEXT_PUBLIC_PICSART_PARENT_DOMAIN` / `VITE_PICSART_PARENT_DOMAIN`) to an **HTTPS** tunnel origin so the SDK can validate the parent window.
+### SDK script URL
 
-## Publish to npm (Picsart org members)
+By default the component loads `https://sdk.picsart.io/cdn.min.js`. If that URL does not match your SDK version, pass **`sdkScriptUrl`** (see [Picsart docs](https://docs.picsart.io/) for the correct `cdn?...` URL).
 
-1. Use an npm account that is a **member of the `@picsart` organization** with publish permission.
-2. From this repository root:
+### Ref (imperative API)
 
-   ```bash
-   npm login
-   npm run build
-   npm run publish:npm
-   ```
+```tsx
+const ref = useRef<PicsartEditorRef>(null);
+<PicsartEditor ref={ref} ... />
+ref.current?.export();
+ref.current?.getInstance();
+```
 
-   This project includes a root **`.npmrc`** so installs and publishes target **`https://registry.npmjs.org/`** for the `@picsart` scope (and avoids accidental publishes to other registries).
+## Publish to npm (`@picsart` org)
 
-3. Scoped packages must be **public** (already set via `publishConfig.access`).
+```bash
+npm whoami
+npm login
+npm run publish:npm
+```
 
-If `npm publish` fails with **403**, your user is not on the `@picsart` org or lacks publish rights—ask your org admin on npmjs.com.
+- Your npm user must be a **member of the `@picsart` organization** with permission to **publish** scoped packages.
+- This repo’s **`.npmrc`** and **`publishConfig.registry`** target **`https://registry.npmjs.org/`** (not GitLab).
 
-## Local example
+If **`npm publish`** returns **404** on `PUT …/@picsart%2freact-photo-editor`, npm is almost always telling you the current login **cannot publish that scope** (or you are not logged in). Fix org membership / use `npm login`, then retry.
+
+To ship a **new** version after changes, bump **`version`** in `package.json`, then run `npm run publish:npm` again.
 
-See the `example/` app: copy `example/.env.example` to `example/.env`, then from repo root:
+## Local example
 
 ```bash
 npm run dev:example
 ```
+
+Configure `example/.env` from `example/.env.example`.

package/dist/index.d.mts

@@ -1,180 +1,120 @@
-import * as react from 'react';
-import { CSSProperties } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { CSSProperties, ReactNode } from 'react';
 
-declare class Picsart {
-    constructor(settings: any);
-    settings: any;
-    provideShapesData: {
-        data: ({
-            id: number;
-            shapeURL: string;
-            previewURL: string;
-            shapeData: {};
-            height: number;
-            width: number;
-            meta_data?: undefined;
-        } | {
-            id: number;
-            shapeURL: string;
-            previewURL: string;
-            meta_data: {};
-            height: number;
-            width: number;
-            shapeData?: undefined;
-        })[];
+type PicsartTheme = 'dark' | 'light';
+type PicsartExportType = 'base64' | 'blob' | 'buffer';
+interface PicsartOpenOptions {
+    replayUrl?: string;
+    templateId?: string;
+    imageUrl?: string;
+    videoUrl?: string;
+    subtitleUrl?: string;
+}
+interface PicsartExportOutput {
+    templateId?: string;
+    data: {
+        replayData?: Blob | ArrayBuffer | string;
+        imageData?: string | Blob;
+        printData?: string | Blob;
+        previewPdfData?: string | Blob;
+        pdfData?: string | Blob;
+        previewsData?: Array<string | Blob>;
+        videoData?: unknown;
+        videoUrl?: string;
     };
-    isEditorReady: boolean;
-    onExportCb: () => void;
-    messageListener: ({ data, origin }: {
-        data: any;
-        origin: any;
-    }) => void;
-    isMessageListenerAttached: boolean;
-    log(...args: any[]): void;
-    onOpen(callback: any): this;
-    openCallBack: any;
-    renderNew(src: any): void;
-    iframe: HTMLIFrameElement | null | undefined;
-    render(src: any): void;
-    close(): this;
-    hide(): void;
-    callCloseHandlers(): void;
-    resetTempData(): void;
-    tempOnClose: any;
-    tempOnExport: any;
-    tempExportType: any;
-    tempExportSettings: any;
-    onClose(cb?: () => void): this;
-    cbClose: (() => void) | undefined;
-    /**
-     * @param {(payload: any) => void} [cb]
-     */
-    onError(cb?: (payload: any) => void): this;
-    cbError: ((payload: any) => void) | undefined;
-    clear(): this;
-    applySettings(settings: any): void;
-    isIframeLoaded(): boolean | null | undefined;
-    onReady(cb?: () => void): this;
-    exportData(payload: any, cb: any): Promise<void>;
-    handleUpload(data: any): void;
-    onUpload(handler: any): void;
-    /**
-     * @param {(result: any) => void} [cb]
-     */
-    onExport(cb?: (result: any) => void): this;
-    export(): void;
-    getEditorSettings(params: any): any;
-    open(params?: {}): this;
-    openOld(params?: {}): this;
-    sendMessage(type: any, data: any): void;
-    attachMessageListener(): void;
-    detachMessageListener(): void;
-    handleMessage({ data, origin }: {
-        data: any;
-        origin: any;
-    }): void;
-    handleEditorReady(): void;
-    flushPendingData(): void;
-    getFetch(url: any): Promise<any>;
-    getCategoriesData(data: any): Promise<any[]>;
-    provideTemplates({ data, dataURL }: {
-        data: any;
-        dataURL: any;
-    }): Promise<this | undefined>;
-    provideTemplatesData: {
-        data: any;
-        dataURL: any;
-    } | undefined;
-    provideShapes({ data, dataURL }: {
-        data: any;
-        dataURL: any;
-    }): Promise<this | undefined>;
-    provideStickerShapes(): Promise<this>;
-    provideTexts({ data, dataURL }: {
-        data: any;
-        dataURL: any;
-    }): Promise<this | undefined>;
-    provideTextsData: {
-        data: any;
-        dataURL: any;
-    } | undefined;
-    provideColors(data: any): this | undefined;
-    provideColorsData: any;
-    providePhotos({ data, dataURL }: {
-        data: any;
-        dataURL: any;
-    }): Promise<this | undefined>;
-    providePhotosData: {
-        data: any;
-        dataURL: any;
-    } | undefined;
-    provideStickers({ data, dataURL }: {
-        data: any;
-        dataURL: any;
-    }): Promise<this | undefined>;
-    provideStickersData: {
-        data: any;
-        dataURL: any;
-    } | undefined;
-    provideFonts({ data, dataURL }: {
-        data: any;
-        dataURL: any;
-    }): Promise<this | undefined>;
-    provideFontsData: {
-        data: any;
-        dataURL: any;
-    } | undefined;
-    provideCanvasSizes({ data, dataURL }: {
-        data: any;
-        dataURL: any;
-    }): Promise<this | undefined>;
-    provideCanvasSizesData: {
-        data: any;
-        dataURL: any;
-    } | undefined;
-    provideLabels(data: any): this | undefined;
-    provideLabelsData: any;
-    provideExportSettings(): void;
+}
+type PicsartUploadHandler = (file: Blob | ArrayBuffer | Uint8Array, mimeType: string) => Promise<{
+    url: string;
+    status: string;
+    progress: number;
+    error: unknown;
+}>;
+interface PicsartInstance {
+    onError(cb: (error: unknown) => void): PicsartInstance;
+    onExport(cb: (output: PicsartExportOutput) => void): PicsartInstance;
+    onClose(cb?: () => void): PicsartInstance;
+    open(options?: PicsartOpenOptions): PicsartInstance;
+    close(): PicsartInstance;
+}
+interface PicsartConstructorOptions {
+    apiKey: string;
+    customerId: string;
+    propertyId: string;
+    containerId: string;
+    exportType?: PicsartExportType;
+    theme?: PicsartTheme;
+    title?: string;
+    selectedCategory?: string;
+    canvasSize?: string;
+    templatesTitleText?: string;
+    templatesSubTitle?: string;
+    replayUrl?: string;
+    videoUrl?: string;
+    imageUrl?: string;
+    subtitleUrl?: string;
+    templateId?: string;
+    stickerText?: string;
+    stickerImageUrl?: string;
+    templatesFilters?: Record<string, unknown>;
+    onUpload?: PicsartUploadHandler;
+}
+interface PicsartConstructor {
+    new (options: PicsartConstructorOptions): PicsartInstance;
+}
+declare global {
+    interface Window {
+        Picsart?: PicsartConstructor;
+    }
 }
 
-type PhotoEditorOpenParams = Record<string, unknown>;
-type PhotoEditorProps = {
+/** Matches Picsart quick-start: apiKey, customerId, propertyId, containerId, title. */
+interface PicsartEditorProps {
+    /** From Picsart signup / dashboard. */
     apiKey: string;
+    /** From Picsart signup / dashboard. */
     customerId: string;
-    propertyId?: string;
+    /** From Picsart signup / dashboard (required for the standard SDK flow). */
+    propertyId: string;
     /**
-     * Full editor entry URL used as the iframe `src` origin (before `?query`).
-     * Use the value from your Picsart onboarding / docs for your SDK version.
+     * Must match the inner editor container’s `id`. If omitted, a stable unique id is generated
+     * and passed to the SDK for you (same as embedding a div with that id).
      */
-    editorDomain?: string;
+    containerId?: string;
     /**
-     * Origin the editor uses as the embedding parent (query `parentDomain`).
-     * **Important:** `http://localhost` often fails SDK origin / postMessage checks.
-     * For local dev use an HTTPS tunnel (ngrok, etc.) and set this to that `https://…` origin,
-     * or set env `NEXT_PUBLIC_PICSART_PARENT_DOMAIN` / `VITE_PICSART_PARENT_DOMAIN`.
+     * Editor chrome title when supported. Defaults to **Photo Print Designer** (Picsart docs default).
      */
-    parentDomain?: string;
+    title?: string;
+    sdkScriptUrl?: string;
     className?: string;
     style?: CSSProperties;
-    title?: string;
+    children?: ReactNode;
+    exportType?: PicsartExportType;
+    theme?: PicsartTheme;
+    selectedCategory?: string;
+    canvasSize?: string;
+    templatesTitleText?: string;
+    templatesSubTitle?: string;
+    templatesFilters?: Record<string, unknown>;
+    replayUrl?: string;
+    videoUrl?: string;
     imageUrl?: string;
-    /** When true (default), merges the bundled CMS-style defaults from `cmsSettings`. */
-    cms?: boolean;
-    debug?: boolean;
-    onExport?: (result: unknown) => void;
-    onError?: (payload: unknown) => void;
+    subtitleUrl?: string;
+    templateId?: string;
+    stickerText?: string;
+    stickerImageUrl?: string;
+    onUpload?: PicsartUploadHandler;
+    onExport?: (output: PicsartExportOutput) => void;
+    onError?: (error: unknown) => void;
     onClose?: () => void;
-    onOpen?: () => void;
-    /** Merged into the Picsart constructor (advanced). */
-    picsartSettings?: Record<string, unknown>;
-    /** Merged into the `.open()` call after mount. */
-    openParams?: PhotoEditorOpenParams;
-};
-type PhotoEditorHandle = {
-    picsart: InstanceType<typeof Picsart> | null;
-    open: (params?: PhotoEditorOpenParams) => InstanceType<typeof Picsart>;
-    close: () => InstanceType<typeof Picsart>;
-};
-declare const PhotoEditor: react.ForwardRefExoticComponent<PhotoEditorProps & react.RefAttributes<PhotoEditorHandle>>;
+    /** When false, `open()` is called with no asset (blank editor). Default true. */
+    autoOpen?: boolean;
+    /** Override initial `open()` payload when autoOpen is true. */
+    openOptions?: PicsartOpenOptions;
+}
+declare function PicsartEditor({ apiKey, customerId, propertyId, containerId: containerIdProp, title, sdkScriptUrl, className, style, children, exportType, theme, selectedCategory, canvasSize, templatesTitleText, templatesSubTitle, templatesFilters, replayUrl, videoUrl, imageUrl, subtitleUrl, templateId, stickerText, stickerImageUrl, onUpload, onExport, onError, onClose, autoOpen, openOptions, }: PicsartEditorProps): react_jsx_runtime.JSX.Element;
+
+declare function loadPicsartSdk(scriptUrl?: string): Promise<void>;
+
+declare function createDefaultVideoUpload(apiKey: string): PicsartUploadHandler;
 
-export { PhotoEditor, type PhotoEditorHandle, type PhotoEditorOpenParams, type PhotoEditorProps, Picsart };
+export { type PicsartConstructorOptions, PicsartEditor, type PicsartEditorProps, type PicsartExportOutput, type PicsartExportType, type PicsartInstance, type PicsartOpenOptions, type PicsartTheme, type PicsartUploadHandler, createDefaultVideoUpload, loadPicsartSdk };