@printine/pod-editor 0.1.20 → 0.1.21

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.
@@ -0,0 +1,137 @@
1
+ # Buyer personalization experience
2
+
3
+ This document describes the buyer personalization workflow included in
4
+ `@printine/pod-editor@0.1.21`. Existing saved customization formats and host
5
+ integration callbacks are preserved. Consuming applications can adopt the
6
+ workflow by upgrading the SDK.
7
+
8
+ ## Merchant flow
9
+
10
+ For `semiDesignPermission={true}`, the former Custom menu is now
11
+ **Personalization**. It starts with a setup guide and a list grouped by print
12
+ placement. Cards display the layer name, thumbnail, fixed/editable state and a
13
+ permission switch. Background color is explicitly labeled as applying to all
14
+ print areas.
15
+
16
+ Select a supported canvas element to see its permission switch and settings
17
+ button beside the normal editing tools. Open settings from either that button
18
+ or its management card. Basic settings contain the buyer-facing label,
19
+ description, text hint and character limit. Advanced settings contain movement,
20
+ color, font and preset choices. Existing linked-element configuration remains
21
+ available, with explicit unlink actions and placement labels.
22
+
23
+ While **Personalization** is active, the floating **Product preview** is hidden;
24
+ its renderer stays mounted and returns when another menu is selected. On screens
25
+ at least 1100 CSS pixels wide, selecting a canvas element or its placement card
26
+ opens a right-hand settings inspector instead of a modal. Each placement also
27
+ has an explicit **Edit** action. The inspector shows the element name, print
28
+ area and permission status. Valid changes apply immediately; incomplete or
29
+ invalid rules display an inline message and keep the last valid rules. Narrower
30
+ screens retain the settings dialog and its explicit Save action. The separate
31
+ buyer preview remains available from either layout.
32
+
33
+ Background color uses the same settings location: its left-hand card only shows
34
+ the permission and status. Selecting it opens the right-hand inspector (or the
35
+ settings dialog on narrow screens), where the merchant manages allowed colors
36
+ and the any-color permission. Its scope remains **All print areas**. Background
37
+ selection clears the canvas element selection; selecting an element switches
38
+ the inspector back to that element. Dialog changes use Save/Cancel, while the
39
+ desktop inspector applies changes immediately. Disabling background
40
+ personalization preserves its color choices for re-enabling.
41
+
42
+ New text/image fields retain the template position, size and styling by default.
43
+ Restored configurations retain their existing permissions, including legacy
44
+ `moveable: true` values and unknown host fields. Switching a field off retains
45
+ its rules only in editor memory, so switching it on restores them. Unmounting
46
+ or switching products clears these temporary drafts. Disabled rules do not
47
+ appear in the saved-style preview document.
48
+
49
+ Ordinary products (`semiDesignPermission={false}`) do not display personalization
50
+ controls. Menu availability is instance-specific; enabling it no longer mutates
51
+ a module-level menu array shared with later products.
52
+
53
+ ## Buyer preview
54
+
55
+ **Preview buyer experience** is a separate action from **Product preview** and
56
+ from the existing Next/Done save workflow. It uses an isolated JSON snapshot,
57
+ `PrintineSemiRenderer`, and `PrintineSemiInteractEditor` for real Fabric text
58
+ fitting, image composition and allowed position changes. Text, font, color,
59
+ image and placement changes do not update the merchant canvas or its history.
60
+
61
+ The preview provides desktop and phone layouts. The phone form includes a
62
+ sticky live thumbnail, so the current product effect remains visible while
63
+ editing lower fields. Print views can be selected explicitly and switch to the
64
+ relevant placement when its input receives focus. Linked fields use one input
65
+ with all affected placement labels and apply edits to all linked targets.
66
+
67
+ When a base plate has no 2D product renders, the preview composes a flat print
68
+ area with the same local Fabric/rendering path and labels it **Print area
69
+ preview**. This is not a 3D material or product mockup. Rendering failures show
70
+ a retry control and are reported through the host's existing `onError` callback
71
+ with code `BUYER_PREVIEW_RENDER_FAILED`.
72
+
73
+ Free image selection uses temporary object URLs in the browser. It never calls
74
+ `adapters.uploadImage`, `onSave`, a cart API or an order API. All preview object
75
+ URLs are revoked when the preview closes. Text updates are serialized, discard
76
+ stale requests and are invalidated on reset/unmount.
77
+
78
+ ## Existing contract
79
+
80
+ The saved `customConfig` and `background_customized` formats are unchanged.
81
+ The implementation uses the existing fields:
82
+
83
+ - `name`, `description`, `hintText`, `maxCount`;
84
+ - `enableOption`, `options` and `syncKey`;
85
+ - `enableOptionalFont`, `optionalFontList` and `enableColor`;
86
+ - `moveable` for movement, resizing and rotation together;
87
+ - background `enable`, `colors` and `palette`.
88
+
89
+ The prototype's independent move/scale switches and required-field proposals
90
+ are not new persisted capabilities in this SDK change. Separate permissions or
91
+ required validation would also need support in the consuming buyer application.
92
+ This implementation presents the combined existing placement permission and
93
+ validates merchant labels, character limits, presets and font choices.
94
+
95
+ The new experience uses the SDK existing localization configuration: English
96
+ by default and its existing Spanish catalog. It adds no locales and does not
97
+ force a `locale` value. Host `locale` and `messages` overrides retain their
98
+ existing precedence. The validation page also omits `locale` by default; its
99
+ optional locale selector is derived from `DESIGNER_MESSAGES`.
100
+
101
+ ## Local verification page
102
+
103
+ From the repository:
104
+
105
+ ```sh
106
+ npm run dev:personalization
107
+ ```
108
+
109
+ Open `http://127.0.0.1:18887/tests/personalization.html`.
110
+
111
+ The page mounts the real source SDK with synthetic, browser-local assets and
112
+ in-memory host adapters. Its LOCAL QA controls switch first-use/configured
113
+ scenarios, language, product mode, and presence of 2D mockups. The unmount button
114
+ releases the editor and its normal unsaved-change guard before reloading the
115
+ fixture during development. No store or credentials are needed.
116
+
117
+ Relevant checks:
118
+
119
+ ```sh
120
+ npm run typecheck
121
+ npm run build
122
+ npm run test:personalization
123
+ npm run test:api
124
+ npm run test:semi-renderer
125
+ npm run test:preview-assets
126
+ npm run test:workspace-pattern
127
+ npm run test:render-preload
128
+ npm run test:print-base
129
+ npm run test:semi-bundle
130
+ npm run pack:check
131
+ ```
132
+
133
+ The new regression checks cover conservative defaults, legacy rule preservation,
134
+ disabled draft reset, linked fields across placements, immutable preview
135
+ snapshots, fixed artwork, per-placement patches, and replacement image bounds.
136
+ The existing API test loader now loads the real personalization helper used by
137
+ the store; its endpoint and credential assertions are unchanged.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@printine/pod-editor",
3
- "version": "0.1.20",
3
+ "version": "0.1.21",
4
4
  "description": "React online product designer with Fabric canvas and host-owned commerce integrations.",
5
5
  "private": false,
6
6
  "keywords": [
@@ -138,6 +138,8 @@
138
138
  "scripts": {
139
139
  "build": "vite build && tsc -p tsconfig.build.json && node ./scripts/copy-declarations.mjs",
140
140
  "typecheck": "tsc --noEmit -p tsconfig.json",
141
+ "test:personalization": "node ./tests/personalization.smoke.mjs",
142
+ "dev:personalization": "vite --host 127.0.0.1 --port 18887 --strictPort",
141
143
  "test:api": "node ./tests/api-client.smoke.mjs && node --test ./tests/editor-assets.smoke.mjs && node ./tests/base-plate.smoke.mjs",
142
144
  "test:preview-assets": "node ./tests/preview-assets.smoke.mjs",
143
145
  "test:workspace-pattern": "node ./tests/workspace-pattern.smoke.mjs",
@@ -1,153 +0,0 @@
1
- import { create as y } from "zustand";
2
- import { HistoryManager as p } from "./engine/history.js";
3
- import { loadFontFile as b } from "./engine/utils/font.js";
4
- import { FONT_WEIGHT as h } from "./engine/constants.js";
5
- let u = null;
6
- function j(e) {
7
- u = e;
8
- }
9
- function l() {
10
- if (!u)
11
- throw new Error(
12
- "[printine-designer] Editor asset API client is not ready. Render <PrintineDesigner /> before calling the API."
13
- );
14
- return u;
15
- }
16
- function r(e) {
17
- return typeof e == "string" ? e : "";
18
- }
19
- function d(e, o) {
20
- return {
21
- data: e,
22
- meta: {
23
- current_page: o?.page ?? 1,
24
- last_page: o?.total_pages ?? 1,
25
- total: o?.total ?? e.length
26
- }
27
- };
28
- }
29
- function w(e) {
30
- const o = [];
31
- for (const t of e) {
32
- const n = [];
33
- for (const s of t.variants ?? []) {
34
- const a = typeof s.weight == "number" ? s.weight : 400, m = s.style === "italic" ? "italic" : "normal", f = `${a}${m === "normal" ? "" : "italic"}`, g = r(s.url);
35
- g && n.push({
36
- style: m,
37
- variant: f,
38
- weight: a,
39
- label: h[f] || `${a}`,
40
- url: g
41
- });
42
- }
43
- const i = r(t.name);
44
- !i || !n.length || o.push({
45
- category: "",
46
- family: i,
47
- variants: [...new Set(n.map((s) => s.variant ?? `${s.weight}`))],
48
- files: n
49
- });
50
- }
51
- return o;
52
- }
53
- function C(e) {
54
- const o = r(e.id), t = r(e.asset_url);
55
- if (!o || !t) return null;
56
- const n = r(e.thumbnail_url);
57
- return { id: o, name: r(e.name), url: t, ...n ? { thumbnailUrl: n } : {} };
58
- }
59
- function S(e) {
60
- return C(e);
61
- }
62
- const k = {
63
- async getFontList() {
64
- const e = await l().get("fonts");
65
- return w(e.data);
66
- },
67
- async getShapeList(e) {
68
- const { size: o, ...t } = e, n = await l().get("shapes", {
69
- ...t,
70
- page: typeof e.page == "number" ? e.page : 1,
71
- limit: typeof o == "number" ? o : 30
72
- }), i = n.data.map(C).filter((s) => s !== null);
73
- return d(i, n.pagination);
74
- },
75
- async getClipArtCategories() {
76
- const o = (await l().get("clipart-categories")).data.map((t) => {
77
- const n = r(t.id);
78
- return n ? {
79
- id: n,
80
- name: r(t.name),
81
- clip_arts: (t.cliparts ?? []).map(S).filter((i) => i !== null)
82
- } : null;
83
- }).filter((t) => t !== null);
84
- return d(o);
85
- }
86
- };
87
- let c = 0;
88
- const A = y((e, o) => ({
89
- currentSide: "",
90
- historyManager: new p(""),
91
- fontList: [],
92
- backgroundColor: "",
93
- colors: [],
94
- activeObjects: [],
95
- rendering: !1,
96
- copiedObjects: null,
97
- semiCustom: {},
98
- semiCustomBackground: { colors: [], palette: !1, enable: !1 },
99
- initData: (t, n) => {
100
- const { getFontList: i, getColors: s } = o();
101
- i(t), s(n);
102
- },
103
- getFontList: async (t) => {
104
- try {
105
- e({ fontList: await (t ? t() : k.getFontList()) });
106
- } catch {
107
- e({ fontList: [] });
108
- }
109
- },
110
- loadMultipleFont: async (t) => {
111
- const { fontList: n } = o(), i = t.map((s) => n.find((a) => a.family === s)).filter((s) => !!s);
112
- await Promise.all(i.map((s) => b(s)));
113
- },
114
- getColors: async (t) => {
115
- const n = ++c;
116
- e({ colors: [] });
117
- try {
118
- const i = t ? await t() : [];
119
- n === c && e({ colors: Array.isArray(i) ? i.filter((s) => typeof s == "string" && s.trim()) : [] });
120
- } catch {
121
- n === c && e({ colors: [] });
122
- }
123
- },
124
- setActiveObjects: (t) => e({ activeObjects: t }),
125
- setCurrentSide: (t) => e({ currentSide: t }),
126
- setBackgroundColor: (t) => e({ backgroundColor: t }),
127
- setHistoryManager: (t) => e({ historyManager: t }),
128
- setRendering: (t) => e({ rendering: t }),
129
- setCopiedObjects: (t) => e({ copiedObjects: t }),
130
- setSemiCustom: (t) => e({ semiCustom: t }),
131
- setSemiCustomItem: (t, n) => e({ semiCustom: { ...o().semiCustom, [t]: n } }),
132
- delSemiCustomInfo: (t) => e({ semiCustom: { ...o().semiCustom, [t]: void 0 } }),
133
- setSemiCustomBackground: (t) => e({ semiCustomBackground: t }),
134
- setSemiCustomBackgroundItem: (t, n) => e({ semiCustomBackground: { ...o().semiCustomBackground, [t]: n } }),
135
- reset: () => {
136
- c += 1, e({
137
- historyManager: new p(""),
138
- activeObjects: [],
139
- backgroundColor: "",
140
- currentSide: "",
141
- copiedObjects: null,
142
- semiCustom: {},
143
- semiCustomBackground: { colors: [], palette: !1, enable: !1 },
144
- colors: []
145
- });
146
- }
147
- })), B = A;
148
- export {
149
- k as A,
150
- B as a,
151
- j as s,
152
- A as u
153
- };