@printine/pod-editor 0.1.14 → 0.1.16
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +27 -45
- package/dist/api/asset-client.d.ts +1 -1
- package/dist/components/context.d.ts +2 -2
- package/dist/components/design.d.ts +2 -2
- package/dist/components/preview/index.d.ts +2 -2
- package/dist/components/semi-renderer.d.ts +3 -1
- package/dist/components/upload-types.d.ts +20 -0
- package/dist/{design-C_TmcalT.js → design-CpQzcaGG.js} +5589 -5595
- package/dist/full-designer.js +2 -3
- package/dist/index.d.ts +1 -3
- package/dist/index.js +134 -146
- package/dist/lib/base-plate.d.ts +3 -0
- package/dist/{pixel-map-dSys7UAx.js → pixel-map-BLlgu5Ix.js} +3 -3
- package/dist/renderer/pixel-map.d.ts +3 -0
- package/dist/renderer/render-layer-output.d.ts +1 -0
- package/dist/{semi-interact-editor-DfzphWy3.js → semi-interact-editor-BVPJX2-9.js} +358 -350
- package/dist/semi-renderer.js +1 -1
- package/dist/style.css +1 -1
- package/dist/types.d.ts +3 -29
- package/docs/HOST_DATA_CONTRACT.md +77 -69
- package/docs/INTEGRATION_API.md +25 -27
- package/docs/SEMI_RENDERER.md +7 -2
- package/package.json +2 -11
- package/dist/api/client.d.ts +0 -8
- package/dist/api/client.js +0 -82
- package/dist/api/common-endpoints.d.ts +0 -12
- package/dist/api/design-endpoints.d.ts +0 -4
- package/dist/api/endpoints.d.ts +0 -23
- package/dist/api/endpoints.js +0 -33
- package/dist/api/files-endpoints.d.ts +0 -1
- package/dist/components/menus/ai.d.ts +0 -5
- package/dist/hooks/use-oss-upload.d.ts +0 -36
package/README.md
CHANGED
|
@@ -6,7 +6,7 @@ the host application owns its own routing, authentication, uploads, user
|
|
|
6
6
|
assets, saved templates and final design persistence.
|
|
7
7
|
|
|
8
8
|
For a complete React integration, including host upload/save implementations,
|
|
9
|
-
start with the [第三方接入文档(React)](
|
|
9
|
+
start with the [第三方接入文档(React)](https://printine.dev/docs).
|
|
10
10
|
|
|
11
11
|
## Install
|
|
12
12
|
|
|
@@ -16,29 +16,22 @@ npm install @printine/pod-editor
|
|
|
16
16
|
|
|
17
17
|
`react` and `react-dom` 18 or 19 are peer dependencies.
|
|
18
18
|
|
|
19
|
-
## Migrating from @printine/designer
|
|
20
|
-
|
|
21
|
-
Replace the dependency with `@printine/pod-editor` and update all import paths,
|
|
22
|
-
including subpaths such as `/styles.css`, `/full-designer` and `/semi-renderer`.
|
|
23
|
-
The `PrintineDesigner` component, exported APIs and CSS selectors are unchanged.
|
|
24
|
-
Existing projects can keep using the previously published `@printine/designer`
|
|
25
|
-
package until they migrate.
|
|
26
|
-
|
|
27
19
|
## Quick start
|
|
28
20
|
|
|
29
21
|
Render the component in the browser on a dedicated page. Replace the example
|
|
30
|
-
|
|
31
|
-
base plate must contain at least one design area and accessible
|
|
22
|
+
product ID with a valid variant ID and supply the complete host-loaded
|
|
23
|
+
`basePlate`. The base plate must contain at least one design area and accessible
|
|
24
|
+
SVG assets. Wait until the base plate is loaded before mounting the editor.
|
|
32
25
|
|
|
33
26
|
```tsx
|
|
34
|
-
import { PrintineDesigner } from '@printine/pod-editor';
|
|
27
|
+
import { PrintineDesigner, type BasePlate } from '@printine/pod-editor';
|
|
35
28
|
import '@printine/pod-editor/styles.css';
|
|
36
29
|
|
|
37
|
-
export function ProductDesigner() {
|
|
30
|
+
export function ProductDesigner({ basePlate }: { basePlate: BasePlate }) {
|
|
38
31
|
return (
|
|
39
32
|
<PrintineDesigner
|
|
40
33
|
productId="variant-id"
|
|
41
|
-
|
|
34
|
+
basePlate={basePlate}
|
|
42
35
|
productInfo={{ title: 'Classic T-shirt', price: 19.9, currency: 'USD' }}
|
|
43
36
|
locale="en-US"
|
|
44
37
|
onClose={() => window.history.back()}
|
|
@@ -47,16 +40,13 @@ export function ProductDesigner() {
|
|
|
47
40
|
}
|
|
48
41
|
```
|
|
49
42
|
|
|
50
|
-
This mounts the editor using the
|
|
51
|
-
|
|
52
|
-
provides `adapters.uploadImage` and `onSave`, respectively.
|
|
53
|
-
[complete upload/save example](./docs/INTEGRATION_API.md#32-带上传与保存的完整示例)
|
|
54
|
-
to connect those capabilities to your backend.
|
|
43
|
+
This mounts the editor using the supplied base plate and the host's same-origin
|
|
44
|
+
asset proxy. Upload and Done controls appear only when the host
|
|
45
|
+
provides `adapters.uploadImage` and `onSave`, respectively.
|
|
55
46
|
|
|
56
47
|
For Next.js App Router, dynamically import the component with
|
|
57
48
|
`next/dynamic({ ssr: false })` inside a Client Component. A `'use client'`
|
|
58
|
-
directive alone does not disable server prerendering.
|
|
59
|
-
[SSR integration example](./docs/INTEGRATION_API.md#33-使用-ssr-框架).
|
|
49
|
+
directive alone does not disable server prerendering.
|
|
60
50
|
|
|
61
51
|
The full editor uses viewport-sized layouts and fixed toolbars. Mount one full
|
|
62
52
|
designer at a time: the current implementation uses shared state and
|
|
@@ -64,11 +54,13 @@ module-level API clients.
|
|
|
64
54
|
|
|
65
55
|
## Integration model
|
|
66
56
|
|
|
67
|
-
The
|
|
68
|
-
base-plate
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
57
|
+
The host must supply `productId` and a complete `basePlate`. The editor never
|
|
58
|
+
fetches base-plate or product data. Product display information comes through
|
|
59
|
+
`productInfo`, and saved designs through `initialDesignData`. Keep the
|
|
60
|
+
`basePlate` object reference stable during editing; replace it when switching
|
|
61
|
+
to a different base plate.
|
|
62
|
+
|
|
63
|
+
Product details, uploads, saved designs and templates are host-owned.
|
|
72
64
|
|
|
73
65
|
Public editor assets default to the embedding page's own origin, through a merchant backend
|
|
74
66
|
proxy at `/api/v1/editor/*`. The merchant server holds its `assets:read` App Key;
|
|
@@ -77,21 +69,18 @@ pass domain-only overrides. The package adds the API paths itself:
|
|
|
77
69
|
|
|
78
70
|
| Prop | Default | SDK-owned path prefix |
|
|
79
71
|
| --- | --- | --- |
|
|
80
|
-
| `apiBaseUrl` | `https://shop-api.printine.com` | `/api/client/` |
|
|
81
72
|
| `assetBaseUrl` | Current page origin (`/`) | `/api/v1/editor/` |
|
|
82
73
|
|
|
83
74
|
`assetBaseUrl` is the merchant resource-service origin, not a CDN/static-image
|
|
84
75
|
prefix. The default `/` resolves to the current browser origin; SSR callers of
|
|
85
76
|
the low-level client must provide an absolute origin. Fonts, shapes and clipart
|
|
86
77
|
categories use `/api/v1/editor/*` without legacy aliases or redirects. Requests
|
|
87
|
-
use `credentials: 'same-origin'` and never send an App Key
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
`token` or `appKey` prop. Printine API responses with business code `445` trigger
|
|
94
|
-
one guest-token recovery and retry; this does not apply to asset requests.
|
|
78
|
+
use `credentials: 'same-origin'` and never send an App Key. The proxy must also
|
|
79
|
+
return browser-accessible merchant file URLs, preserving filename suffixes and
|
|
80
|
+
resource `v` references. Cross-origin overrides do not automatically send cookies
|
|
81
|
+
to the other origin. Use a same-origin proxy or supply custom `adapters.library`
|
|
82
|
+
loaders when your resource service needs different authentication. The package
|
|
83
|
+
has no top-level `token` or `appKey` prop.
|
|
95
84
|
|
|
96
85
|
Hosts may supply `adapters.library` for normalized fonts, shapes and clipart.
|
|
97
86
|
Preset colours are host-owned: provide `adapters.library.colors.list` to return
|
|
@@ -179,7 +168,7 @@ plate's `areas[].name`. Restore semi-custom background settings separately
|
|
|
179
168
|
through `initialBackgroundCustomized`. Use `loading={true}` while fetching a
|
|
180
169
|
record, then initialize the editor with the loaded data. These are initial
|
|
181
170
|
values, not controlled canvas state; change the component `key` when switching
|
|
182
|
-
records or base plates.
|
|
171
|
+
records or base plates.
|
|
183
172
|
|
|
184
173
|
### Preview rendering
|
|
185
174
|
|
|
@@ -231,13 +220,6 @@ for integration, including `PrintineDesignerProps`, `DesignerAdapters`,
|
|
|
231
220
|
`DesignerAsset`, `DesignerUserTemplate` and `DesignerSaveInput`.
|
|
232
221
|
|
|
233
222
|
`@printine/pod-editor/full-designer` is available for advanced integrations that
|
|
234
|
-
already provide a designer runtime. The main entry also exports
|
|
223
|
+
already provide a designer runtime and the required `basePlate` prop. The main entry also exports
|
|
235
224
|
`PrintineSemiRenderer` for standalone local preview rendering and
|
|
236
|
-
`PrintineSemiInteractEditor` for semi-custom editing.
|
|
237
|
-
[semi-custom renderer documentation](./docs/SEMI_RENDERER.md) for usage.
|
|
238
|
-
|
|
239
|
-
## Documentation
|
|
240
|
-
|
|
241
|
-
- [第三方接入文档(React)](./docs/INTEGRATION_API.md): installation, complete React example, properties, upload/save/restore flows, asset proxy, events and troubleshooting.
|
|
242
|
-
- [Host data contract](./docs/HOST_DATA_CONTRACT.md): host product display data, design restoration, base-plate data, merchant asset proxy and optional palette.
|
|
243
|
-
- [Semi-custom renderer](./docs/SEMI_RENDERER.md): standalone rendering, resource preloading, incremental updates and interactive editing.
|
|
225
|
+
`PrintineSemiInteractEditor` for semi-custom editing.
|
|
@@ -3,6 +3,6 @@ import type { AssetCenterApiClient, AssetCenterApiClientOptions } from '../types
|
|
|
3
3
|
export declare const DEFAULT_PRINTINE_ASSET_BASE_URL = "/";
|
|
4
4
|
/**
|
|
5
5
|
* Read-only merchant editor-asset proxy client. No App Key or internal token
|
|
6
|
-
* reaches the browser.
|
|
6
|
+
* reaches the browser.
|
|
7
7
|
*/
|
|
8
8
|
export declare function createAssetCenterApiClient(options: AssetCenterApiClientOptions): AssetCenterApiClient;
|
|
@@ -2,7 +2,7 @@ import Editor from '../engine/editor';
|
|
|
2
2
|
import EventManager from '../engine/managers/event';
|
|
3
3
|
import { Product, BasePlate } from '../contracts/api-design';
|
|
4
4
|
import React from 'react';
|
|
5
|
-
import {
|
|
5
|
+
import type { PersistImage } from './upload-types';
|
|
6
6
|
type DesignContextType = {
|
|
7
7
|
canvasEditor: React.RefObject<Editor | null>;
|
|
8
8
|
eventManager: React.RefObject<EventManager | null>;
|
|
@@ -11,7 +11,7 @@ type DesignContextType = {
|
|
|
11
11
|
currentViewName: string;
|
|
12
12
|
viewColors: Record<string, string>;
|
|
13
13
|
setViewColors: React.Dispatch<React.SetStateAction<Record<string, string>>>;
|
|
14
|
-
onPersistImage:
|
|
14
|
+
onPersistImage: PersistImage;
|
|
15
15
|
onChangeView: (placement: string) => Promise<void>;
|
|
16
16
|
setCanvasLoading: React.Dispatch<React.SetStateAction<boolean>>;
|
|
17
17
|
};
|
|
@@ -2,8 +2,8 @@ import { BasePlate } from '../contracts/api-design';
|
|
|
2
2
|
export interface FullDesignerProps {
|
|
3
3
|
/** Enables the optional semi-customization menu supplied by the existing API. */
|
|
4
4
|
semiDesignPermission?: boolean;
|
|
5
|
-
/**
|
|
6
|
-
basePlate
|
|
5
|
+
/** Complete base plate supplied by the host. */
|
|
6
|
+
basePlate: BasePlate;
|
|
7
7
|
}
|
|
8
8
|
declare const Design: ({ semiDesignPermission, basePlate }: FullDesignerProps) => import("react").JSX.Element;
|
|
9
9
|
export default Design;
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import React from 'react';
|
|
2
2
|
import { Product, Render, TDRender, TDRenderArea } from '../../contracts/api-design';
|
|
3
|
-
import {
|
|
3
|
+
import type { UploadDesignData } from '../upload-types';
|
|
4
4
|
type PreviewType = '3d' | 'graphic' | 'graphicRealTime' | 'graphicLayered';
|
|
5
5
|
interface PreviewDialogProps {
|
|
6
6
|
onClose?: () => void;
|
|
@@ -14,7 +14,7 @@ interface PreviewDialogProps {
|
|
|
14
14
|
designData?: Record<string, any>;
|
|
15
15
|
hasEmptyView?: boolean;
|
|
16
16
|
index?: number;
|
|
17
|
-
onOssUpload?:
|
|
17
|
+
onOssUpload?: UploadDesignData;
|
|
18
18
|
}
|
|
19
19
|
export default function PreviewDialog({ onClose, type, tdModel, areas, renderParams, imageList, renderList, product, designData, index, hasEmptyView, onOssUpload, }: PreviewDialogProps): React.JSX.Element;
|
|
20
20
|
export type { PreviewDialogProps, PreviewType };
|
|
@@ -49,7 +49,9 @@ export interface PrintineSemiRendererProps {
|
|
|
49
49
|
preloadDesignData?: SemiRendererDesignData;
|
|
50
50
|
/** A cached object URL usable by host loading UI. Valid for this component's resource session. */
|
|
51
51
|
onAssetReady?: (source: string, url: string) => void;
|
|
52
|
-
/**
|
|
52
|
+
/** `global` preserves the legacy first-printable-color behavior; `placement` keeps fills local. */
|
|
53
|
+
colorMode?: 'global' | 'placement';
|
|
54
|
+
/** Explicit global fill override, including an empty string, in either color mode. */
|
|
53
55
|
backgroundColor?: string;
|
|
54
56
|
/** Resolution factor passed to the local Sticker renderer. */
|
|
55
57
|
scale?: number;
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import type { Size } from '../contracts/design';
|
|
2
|
+
/** Internal bridge to the host's design-data upload adapter. */
|
|
3
|
+
export type UploadDesignData = (input: {
|
|
4
|
+
file?: File;
|
|
5
|
+
base64Str?: string | null;
|
|
6
|
+
path?: string;
|
|
7
|
+
}) => Promise<string | null>;
|
|
8
|
+
/** Internal bridge to the host's image-library upload adapter. */
|
|
9
|
+
export type PersistImage = (input: {
|
|
10
|
+
file?: File;
|
|
11
|
+
base64Str?: string;
|
|
12
|
+
transform?: boolean;
|
|
13
|
+
size: Size;
|
|
14
|
+
}) => Promise<{
|
|
15
|
+
originalPath: string;
|
|
16
|
+
thumbnailPath: string | null;
|
|
17
|
+
canvasThumbnailPath?: string;
|
|
18
|
+
thumbnailScale?: number;
|
|
19
|
+
assetId?: string;
|
|
20
|
+
} | null>;
|