@charisol/plexo-sdk 2.0.28 → 2.0.29
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 +301 -0
- package/dist/{InlineColorPicker-BYcOgLVc.js → InlineColorPicker-XesBzRsU.js} +362 -114
- package/dist/{v1-Cz7qypQd.js → blank-BEl6CY5C.js} +4656 -10906
- package/dist/brandGuide-Dd4fqVjS.js +33 -0
- package/dist/{client-DUSU8g5z.js → client-CWui0-3q.js} +1 -1
- package/dist/codeEditor-Cux0ud2j.js +205 -0
- package/dist/files-Df6FY0HK.js +2182 -0
- package/dist/id-CR6Y8qD6.js +8 -0
- package/dist/index.js +12786 -13034
- package/dist/{brandGuide-DgoZ7spo.js → lint-CV3DmM0X.js} +78 -109
- package/dist/pdfImport-BOev0Pc1.js +262 -0
- package/dist/plexo-sdk.css +1 -1
- package/dist/v1-Cn7SGvZk.js +6253 -0
- package/dist/v2/CanvasEditor.d.ts +25 -0
- package/dist/v2/V2Editor.d.ts +15 -20
- package/dist/v2/compile/build.d.ts +5 -0
- package/dist/v2/components/properties/PropertiesPanel.d.ts +1 -0
- package/dist/v2/files/aiPicture.d.ts +85 -0
- package/dist/v2/files/build.d.ts +49 -0
- package/dist/v2/files/capture.d.ts +52 -0
- package/dist/v2/files/convert.d.ts +24 -0
- package/dist/v2/files/docx.d.ts +1 -0
- package/dist/v2/files/engine.d.ts +2 -0
- package/dist/v2/files/export.d.ts +97 -0
- package/dist/v2/files/import.d.ts +34 -0
- package/dist/v2/files/index.d.ts +16 -0
- package/dist/v2/files/pdf.d.ts +15 -0
- package/dist/v2/files/pdfImport.d.ts +28 -0
- package/dist/v2/files/sheet.d.ts +16 -0
- package/dist/v2/files/text.d.ts +8 -0
- package/dist/v2/files/types.d.ts +96 -0
- package/dist/v2/files/ui/ExportDock.d.ts +11 -0
- package/dist/v2/files/ui/ExportMenu.d.ts +5 -0
- package/dist/v2/files/ui/ExportPanel.d.ts +17 -0
- package/dist/v2/files/ui/FileEditor.d.ts +14 -0
- package/dist/v2/files/ui/HtmlWorkbench.d.ts +15 -0
- package/dist/v2/files/ui/codeEditor.d.ts +12 -0
- package/dist/v2/files/ui/editors.d.ts +28 -0
- package/dist/v2/files/vector.d.ts +19 -0
- package/dist/v2/files/zip.d.ts +10 -0
- package/dist/v2/host/HostContext.d.ts +6 -3
- package/dist/v2/index.d.ts +5 -1
- package/dist/v2-compile.js +17 -16
- package/dist/v2-files.js +3 -0
- package/dist/v2-strata.js +2 -2
- package/dist/v2.js +5805 -4038
- package/package.json +18 -3
package/README.md
CHANGED
|
@@ -14,6 +14,7 @@
|
|
|
14
14
|
- 🤖 **AI content generation** — edit a single element, edit the whole layout, or generate a fresh layout from a prompt, with support for OpenAI, Gemini, and Claude
|
|
15
15
|
- 🔒 **Server-proxied AI, no exposed keys** — your provider API key is never sent to or stored in the browser; every AI request is authenticated with your Plexo API key and resolved against your account's server-side configuration
|
|
16
16
|
- 💬 **Claude-Code-style AI feedback** — a loading bubble followed by a one-line summary of what changed, for both the per-element editor and the layout prompt bar
|
|
17
|
+
- 📁 **File editor & export** — open or create designs, HTML (with a code editor), documents, text, Markdown, spreadsheets, PDFs and pictures; export to PNG, JPG, PDF, SVG, DOCX, XLSX and more, including a Figma-style export from the landing-page canvas (see [File editor & export](#file-editor--export-v2))
|
|
17
18
|
- 🖼️ **Stock image search** — Unsplash, Pexels, Pixabay integrations
|
|
18
19
|
- 🎨 **Design token system** — Strata token support for consistent brand theming
|
|
19
20
|
- 📦 **ESM-only, pure client-side component** — nothing to self-host; the SDK talks directly to Plexo's hosted API for AI/publish/compile using your Plexo API key
|
|
@@ -319,6 +320,305 @@ The previous V2 (`V2Canvas`, `useCanvasStore`, `compilePageToReact(nodes, pageOr
|
|
|
319
320
|
|
|
320
321
|
---
|
|
321
322
|
|
|
323
|
+
## File editor & export (v2)
|
|
324
|
+
|
|
325
|
+
Everything in this section ships in `@charisol/plexo-sdk/v2` (the editor) and `@charisol/plexo-sdk/v2/files` (the same engine without any UI).
|
|
326
|
+
|
|
327
|
+
### Quick start
|
|
328
|
+
|
|
329
|
+
```bash
|
|
330
|
+
npm install @charisol/plexo-sdk # one package; the PDF reader and code editor are included and load only when needed
|
|
331
|
+
```
|
|
332
|
+
|
|
333
|
+
```tsx
|
|
334
|
+
'use client'; // the editor runs in the browser (in Next.js, load it with next/dynamic and ssr: false)
|
|
335
|
+
import { V2Editor } from '@charisol/plexo-sdk/v2';
|
|
336
|
+
import '@charisol/plexo-sdk/dist/plexo-sdk.css';
|
|
337
|
+
|
|
338
|
+
export default function Files() {
|
|
339
|
+
return (
|
|
340
|
+
<div style={{ height: '100vh' }}> {/* the editor fills its container, so give the parent a height */}
|
|
341
|
+
<V2Editor mode="file" /> {/* that's it: start screen, editors, preview and Export all work with no other props */}
|
|
342
|
+
</div>
|
|
343
|
+
);
|
|
344
|
+
}
|
|
345
|
+
```
|
|
346
|
+
|
|
347
|
+
With no other props, people can create or open files and **Export** them (downloads). Add what your app needs:
|
|
348
|
+
|
|
349
|
+
| You want to… | Pass |
|
|
350
|
+
|---|---|
|
|
351
|
+
| Get the finished file back in your app (upload it, store it) | `files={{ onSaveFile }}` → shows **Save** |
|
|
352
|
+
| Choose what they make yourself, or open a given file | `files={{ kind }}` or `files={{ file }}` (see "Using your own screens") |
|
|
353
|
+
| Store pictures the editor makes on your storage instead of embedding them | `onUpload={(file) => url}` |
|
|
354
|
+
| Turn pictures into editable designs with AI | nothing inside the Plexo dashboard; elsewhere `files={{ imageAi }}` |
|
|
355
|
+
| Match your brand | `theme={{ accent, background, text }}` |
|
|
356
|
+
| Only export from the landing-page / email canvas | nothing — it's already there (section 1) |
|
|
357
|
+
|
|
358
|
+
Things that are **not** needed: an API key (only for the AI inside the Plexo dashboard), a server, or any build configuration.
|
|
359
|
+
|
|
360
|
+
### 1. Export from the landing-page / email canvas
|
|
361
|
+
|
|
362
|
+
Nothing to set up — every `V2Editor` has it. Click an element (or several, or nothing for the whole page) and use the **Export** section under the right-hand panel (shortcut ⇧⌘E / Ctrl+Shift+E), or the Export button in the top bar.
|
|
363
|
+
|
|
364
|
+
| You get | How |
|
|
365
|
+
|---|---|
|
|
366
|
+
| PNG, JPG, PDF, SVG | One or more rows of *size + format* (1x–4x), then **Export**. Several rows download as one zip. |
|
|
367
|
+
| Just part of a page | The selection is cut out like Figma does: one element, or several together as one picture. Nothing selected = the whole page at the current screen size (desktop / tablet / phone). |
|
|
368
|
+
| PDF | One long page, or split into A4 pages. |
|
|
369
|
+
| SVG | **Editable shapes and text** (default; opens in Figma / Illustrator) or **Exact look** (the browser's own drawing wrapped in an SVG). Rotation, gradients (linear, radial, conic), shadows (several, inset, text), gradient text, filters, tiled backgrounds, form fields and list bullets are all drawn. Embedded videos/maps from other sites appear as a grey play-mark box, and frosted-glass blur isn't possible in SVG; the owner is told when either is present. |
|
|
370
|
+
| Emails | Exported whole, as they will be sent. |
|
|
371
|
+
|
|
372
|
+
Hide the top-bar button with `features={{ exportMenu: false }}` (the panel stays). Pictures hosted on another site must allow copying (CORS) to be included; the owner sees a plain-words warning when one can't be.
|
|
373
|
+
|
|
374
|
+
### 2. The file editor — `mode="file"` and `mode="hybrid"`
|
|
375
|
+
|
|
376
|
+
Pass a flag and the editor opens as a **file editor** instead of the page builder, the same way `mode="email"` switches it to emails:
|
|
377
|
+
|
|
378
|
+
```tsx
|
|
379
|
+
import { V2Editor } from '@charisol/plexo-sdk/v2';
|
|
380
|
+
|
|
381
|
+
<V2Editor
|
|
382
|
+
mode="file" // or "hybrid"
|
|
383
|
+
apiKey="workspace-internal" // inside the Plexo dashboard — turns the built-in AI on (see below)
|
|
384
|
+
onUpload={uploadImage} // optional: where pictures made by the editor are stored (else they're embedded)
|
|
385
|
+
files={{
|
|
386
|
+
file, // optional: a File/Blob to open, or a FileSource you saved before
|
|
387
|
+
kind: 'design', // optional: start a new file of this kind
|
|
388
|
+
onSaveFile: async (r) => { // optional: shows Save; called with the finished file
|
|
389
|
+
await upload(r.blob, r.filename); // r.blob is in the format the person chose
|
|
390
|
+
await db.save(r.source); // r.source reopens it later: files={{ file: r.source }}
|
|
391
|
+
},
|
|
392
|
+
onClose: () => router.back(), // optional: shows a Back button
|
|
393
|
+
}}
|
|
394
|
+
/>
|
|
395
|
+
```
|
|
396
|
+
|
|
397
|
+
- **`mode="file"`** — Design (a single-page visual canvas), **HTML** (a web page as code), Document, Text, Markdown and Sheet.
|
|
398
|
+
- **`mode="hybrid"`** — the same, plus Email, and the design view keeps your full page tooling (page list, branding, library; pass `pageSource`, `features` etc. as usual).
|
|
399
|
+
- With no `file` or `kind` the person sees a start screen: pick a type, or drop in a file.
|
|
400
|
+
|
|
401
|
+
**What the person can do**
|
|
402
|
+
|
|
403
|
+
- **Switch type** with the toggle at the top: the content is converted (and Undo is offered). **Text** is plain text only: no design tools, no preview.
|
|
404
|
+
- **HTML files** open exactly as written (nothing stripped or rewritten) in a code editor with syntax colours for HTML, CSS and JavaScript, auto-closing tags, indent, folding and search, with the page live beside it (computer / tablet / phone width). Paste a whole page or a fragment, edit it, then Export or Save as PNG, PDF, SVG and more; what's exported is what the preview shows (scripts don't run). The editor engine (CodeMirror) loads only when an HTML file is opened. A design's HTML tab has **Edit this as HTML** to turn it into a code file.
|
|
405
|
+
- **Switch view**: Visual / HTML / Preview. Preview is the picture an export would make. A Document's HTML is editable.
|
|
406
|
+
- **Open** PDF, pictures (PNG, JPG, WebP, GIF, SVG), `.docx`, `.xlsx`, `.csv`, `.html` (as code), `.md`, `.txt`.
|
|
407
|
+
- **Export** (downloads) and **Save** (sends to your app via `onSaveFile`) in: PNG, JPG, PDF, SVG, HTML, TXT, MD, DOCX, CSV, XLSX. The formats offered depend on the type; limit them with `files.saveFormats`.
|
|
408
|
+
- **Spreadsheets** have a grid with formulas (`=SUM(A1:A5)`, `+ − × ÷`, `AVERAGE MIN MAX COUNT ROUND ABS SQRT`), paste from Excel/Sheets, and `.xlsx` / `.csv` export.
|
|
409
|
+
|
|
410
|
+
**What a saved file looks like**
|
|
411
|
+
|
|
412
|
+
```ts
|
|
413
|
+
// What onSaveFile receives
|
|
414
|
+
interface FileSaveResult {
|
|
415
|
+
kind: FileKind; // 'design' | 'email' | 'html' | 'document' | 'text' | 'markdown' | 'sheet'
|
|
416
|
+
name: string; // without extension
|
|
417
|
+
format: ExportFormat; // what they chose: 'png' | 'jpeg' | 'pdf' | 'svg' | 'html' | 'txt' | 'md' | 'docx' | 'csv' | 'xlsx'
|
|
418
|
+
filename: string; // "Quarterly report.pdf"
|
|
419
|
+
blob: Blob; // the finished file: upload this
|
|
420
|
+
source: FileSource; // the editable version: store this, reopen it later with files={{ file: source }}
|
|
421
|
+
warnings: string[]; // plain-words notes for the person (e.g. a picture that couldn't be included)
|
|
422
|
+
}
|
|
423
|
+
|
|
424
|
+
// FileSource is plain JSON, safe to keep in your database
|
|
425
|
+
type FileSource =
|
|
426
|
+
| { kind: 'design' | 'email'; name: string; content: PageDefinition[] } // pages from the visual canvas
|
|
427
|
+
| { kind: 'html' | 'document' | 'text' | 'markdown'; name: string; content: string }
|
|
428
|
+
| { kind: 'sheet'; name: string; content: string[][] }; // rows of cells ("=SUM(A1:A3)" for formulas)
|
|
429
|
+
```
|
|
430
|
+
|
|
431
|
+
**`files` options**
|
|
432
|
+
|
|
433
|
+
| Option | What it does |
|
|
434
|
+
|---|---|
|
|
435
|
+
| `file` | `File` / `Blob` to open (type detected from its name), or a `FileSource` returned earlier by `onSaveFile`. |
|
|
436
|
+
| `fileName` | Name to use when `file` is an unnamed Blob. |
|
|
437
|
+
| `kind` | Start a new file of `'design' \| 'email' \| 'html' \| 'document' \| 'text' \| 'markdown' \| 'sheet'`. |
|
|
438
|
+
| `kinds` | Which types to offer. |
|
|
439
|
+
| `saveFormats` | Formats under "Save as". |
|
|
440
|
+
| `onSaveFile(result)` | Save button. `result` = `{ kind, name, format, filename, blob, source, warnings }`. |
|
|
441
|
+
| `onClose` | Back button. |
|
|
442
|
+
| `onConvertImage`, `imageAi`, `aiConversion` | AI picture conversion — see below. |
|
|
443
|
+
|
|
444
|
+
### Using your own screens (you choose, we edit)
|
|
445
|
+
|
|
446
|
+
You don't have to use our "What would you like to make?" screen. Decide in your own UI, then hand the editor the result; it handles everything after that (the editing screens, preview, export, save) in your colours.
|
|
447
|
+
|
|
448
|
+
```tsx
|
|
449
|
+
import { V2Editor, type V2EditorHandle } from '@charisol/plexo-sdk/v2';
|
|
450
|
+
const ref = useRef<V2EditorHandle>(null);
|
|
451
|
+
|
|
452
|
+
// 1. Your chooser decided: open straight into it. No start screen, and no type switch if the type shouldn't change.
|
|
453
|
+
<V2Editor ref={ref} mode="file" theme={{ accent: '#7c3aed', background: '#ffffff', text: '#111827' }}
|
|
454
|
+
files={{ kind: 'html', showTypeSwitcher: false, onSaveFile: save }} />
|
|
455
|
+
|
|
456
|
+
// 2. Or hand it a file the person picked or you stored (File/Blob of any supported type, or a FileSource).
|
|
457
|
+
<V2Editor mode="file" files={{ file: pickedFile, showTypeSwitcher: false }} />
|
|
458
|
+
|
|
459
|
+
// 3. Or keep one mounted editor and drive it: switching is also just a prop change (`files.kind` / `files.file`).
|
|
460
|
+
await ref.current.open(file); // open a file, replacing what is open
|
|
461
|
+
ref.current.create('sheet', 'Budget'); // a new empty file
|
|
462
|
+
const source = ref.current.getSource(); // store this; reopen later with files={{ file: source }}
|
|
463
|
+
const png = await ref.current.exportAs('png', { scale: 2 }); // { blob, filename, warnings }, nothing saved anywhere
|
|
464
|
+
await ref.current.save('pdf'); // through your onSaveFile
|
|
465
|
+
```
|
|
466
|
+
|
|
467
|
+
| Option | What it does |
|
|
468
|
+
|---|---|
|
|
469
|
+
| `files.startScreen: false` | Never show our chooser. With nothing given, a new file of the first of `kinds` opens. |
|
|
470
|
+
| `files.kind` / `files.file` | What to open. Followed as they change, not read once. |
|
|
471
|
+
| `files.showTypeSwitcher: false` | Hide the Design / HTML / Document… switch. |
|
|
472
|
+
| `files.kinds` | Which types exist (also limits the switch). |
|
|
473
|
+
| `headerLeft` / `headerRight` | Your own controls in the editor's top bar. |
|
|
474
|
+
| `theme` | `{ accent, background, text }`: every shade (panels, borders, hover, muted text) is mixed from these, and a light background works as well as a dark one. |
|
|
475
|
+
|
|
476
|
+
### 3. Opening a PDF for editing
|
|
477
|
+
|
|
478
|
+
A PDF opens as a multi-page design (up to 30 pages): each page is drawn as a picture with its words wiped out, and the words are placed on top as **real, movable, editable text** (position, size, colour, bold/italic and font family are carried over). **Export → PDF** writes every page back. A **scanned** PDF has no words to read, so each page goes through the AI picture conversion below (up to 10 pages), or is placed as a picture when AI isn't available. Password-protected PDFs are refused with a plain message. The PDF reader (`pdfjs-dist`) is loaded only when a PDF is opened. Your bundler must be able to resolve it (it is a dependency of this package; with Next.js nothing extra is needed).
|
|
479
|
+
|
|
480
|
+
### 4. Turning a picture into an editable design (AI)
|
|
481
|
+
|
|
482
|
+
When someone opens a picture (or a scanned PDF page), a vision model describes its parts — text, boxes, photos with positions — and the editor rebuilds them as real elements. Photos are cut out of the original, never redrawn. The person can **Skip** while it works and **Undo** afterwards to get the original picture on the canvas.
|
|
483
|
+
|
|
484
|
+
- **Inside the Plexo dashboard** (`apiKey="workspace-internal"`): built in. It calls `POST /api/v1/ai/image-to-design` on plexo-web, which uses the account's AI credits/keys. Nothing to pass.
|
|
485
|
+
- **Elsewhere**, give the editor a way to reach a vision model — the simplest is `imageAi`, which only sends the picture and returns the model's JSON:
|
|
486
|
+
|
|
487
|
+
```tsx
|
|
488
|
+
import { IMAGE_TO_DESIGN_PROMPT } from '@charisol/plexo-sdk/v2/files';
|
|
489
|
+
|
|
490
|
+
<V2Editor
|
|
491
|
+
mode="file"
|
|
492
|
+
files={{
|
|
493
|
+
imageAi: async ({ image, width, height }) => {
|
|
494
|
+
// `image` is a JPEG data URL, at most 1600px. Send it to YOUR server, which calls a vision model with
|
|
495
|
+
// IMAGE_TO_DESIGN_PROMPT (replace {width}/{height}) as the system prompt, and return the parsed JSON.
|
|
496
|
+
const res = await fetch('/my-api/rebuild', { method: 'POST', body: JSON.stringify({ image, width, height }) });
|
|
497
|
+
return (await res.json()).spec;
|
|
498
|
+
},
|
|
499
|
+
}}
|
|
500
|
+
/>
|
|
501
|
+
```
|
|
502
|
+
|
|
503
|
+
The SDK validates the answer (colours, sizes and counts are checked; anything unusable is dropped), so the model's output is never trusted. For full control pass `onConvertImage(input) => Promise<PageDefinition[]>` instead.
|
|
504
|
+
- **Without AI** a picture is placed on the canvas as one image the person can crop, resize and put text over. Turn the AI off with `aiConversion: false`.
|
|
505
|
+
|
|
506
|
+
### 5. Use the engine without the editor
|
|
507
|
+
|
|
508
|
+
```ts
|
|
509
|
+
import { exportSource, downloadResult, openFile, convertContent } from '@charisol/plexo-sdk/v2/files';
|
|
510
|
+
|
|
511
|
+
// Export a landing page, or just one element of it
|
|
512
|
+
const png = await exportSource({ kind: 'design', page, nodeIds: [heroId] }, { format: 'png', scale: 2 });
|
|
513
|
+
downloadResult(png); // { blob, filename, mime, warnings }
|
|
514
|
+
|
|
515
|
+
// Every page of a multi-page design as one PDF
|
|
516
|
+
await exportSource({ kind: 'design', page: pages[0], pages }, { format: 'pdf' });
|
|
517
|
+
|
|
518
|
+
// Documents, text, Markdown and spreadsheets
|
|
519
|
+
await exportSource({ kind: 'html', name: 'Notes', body: '<h1>Hi</h1>' }, { format: 'docx' });
|
|
520
|
+
// A whole web page, drawn exactly as the browser shows it
|
|
521
|
+
await exportSource({ kind: 'rawhtml', name: 'Landing', html: pastedHtml, width: 1200 }, { format: 'png' });
|
|
522
|
+
await exportSource({ kind: 'sheet', name: 'Budget', grid: [['a', 'b'], ['1', '=A2*2']] }, { format: 'xlsx' });
|
|
523
|
+
|
|
524
|
+
// Open any supported file
|
|
525
|
+
const opened = await openFile(file); // → source | image | pdf
|
|
526
|
+
```
|
|
527
|
+
|
|
528
|
+
`ExportOptions`: `format`, `scale` (1–4), `background` (`null` = see-through), `quality`, `svgMode` (`'vector' \| 'exact'`), `pdfPaging` (`'single' \| 'a4'`), `filename`. Everything here runs **in the browser** (pages are drawn with the browser's own engine) and returns a plain `Blob`.
|
|
529
|
+
|
|
530
|
+
### 6. A complete host integration, end to end
|
|
531
|
+
|
|
532
|
+
[`examples/host-integration`](examples/host-integration) is a small, runnable host app ("Acme Studio") with its own backend. It is tested end to end in a real browser: the host's own chooser, create, edit, Save to the host's storage, list, download, reopen from the saved source, re-save without duplicating, and picture upload / AI. Run it:
|
|
533
|
+
|
|
534
|
+
```bash
|
|
535
|
+
npm install && npm run build # once
|
|
536
|
+
ANTHROPIC_API_KEY=sk-ant-… npm run example # key is optional: without it the picture rebuild shows a plain "not set up" message
|
|
537
|
+
# web app on http://localhost:5181, backend on :5180
|
|
538
|
+
```
|
|
539
|
+
|
|
540
|
+
What the host builds is four small pieces. Everything else (the editors, preview, export, formats, theming) is the SDK's.
|
|
541
|
+
|
|
542
|
+
**1. Its own screens, then hand over to the editor**
|
|
543
|
+
|
|
544
|
+
```tsx
|
|
545
|
+
// "My files" + a chooser are YOUR screens. When someone picks, mount the editor with the answer:
|
|
546
|
+
<V2Editor
|
|
547
|
+
mode="file"
|
|
548
|
+
theme={{ accent: '#7c3aed', background: '#ffffff', text: '#1f2937' }} // your brand: three colours
|
|
549
|
+
onUpload={uploadPicture} // 2. your storage for pictures the editor makes
|
|
550
|
+
files={{
|
|
551
|
+
kind: 'html', // new file of this type… or file: savedSource / aFile to open one
|
|
552
|
+
startScreen: false, // you have your own chooser
|
|
553
|
+
showTypeSwitcher: false, // the type was chosen on your screen
|
|
554
|
+
imageAi: describePicture, // 3. your AI
|
|
555
|
+
onSaveFile: (r) => save(r, existingId), // 4. your save
|
|
556
|
+
defaultSaveFormat: 'png', // optional: keep saving in the format this file was saved in
|
|
557
|
+
onClose: () => showMyFiles(), // Back button
|
|
558
|
+
}}
|
|
559
|
+
/>
|
|
560
|
+
```
|
|
561
|
+
|
|
562
|
+
**2. Storage for pictures the editor makes** (cut-out photos, PDF pages). Return where you stored each:
|
|
563
|
+
|
|
564
|
+
```ts
|
|
565
|
+
const uploadPicture = async (file: File) => {
|
|
566
|
+
const body = new FormData(); body.append('file', file);
|
|
567
|
+
const res = await fetch('/api/upload', { method: 'POST', body });
|
|
568
|
+
if (!res.ok) throw new Error('The picture could not be uploaded.'); // shown to the person
|
|
569
|
+
return (await res.json()).url;
|
|
570
|
+
};
|
|
571
|
+
// Without onUpload, small pictures are embedded in the design instead (fine for trying it out).
|
|
572
|
+
```
|
|
573
|
+
|
|
574
|
+
**3. AI for pictures** (optional). The editor sends a picture; your server asks a vision model with the prompt the SDK ships and returns its JSON:
|
|
575
|
+
|
|
576
|
+
```ts
|
|
577
|
+
// client
|
|
578
|
+
const describePicture = async ({ image, width, height, signal }) => {
|
|
579
|
+
const res = await fetch('/api/rebuild-picture', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ image, width, height }), signal });
|
|
580
|
+
const out = await res.json();
|
|
581
|
+
if (!res.ok) throw new Error(out.error); // plain words: the person sees this, and their picture is placed on the canvas instead
|
|
582
|
+
return out.spec;
|
|
583
|
+
};
|
|
584
|
+
|
|
585
|
+
// server (Node; any language works: it only needs to call a vision model)
|
|
586
|
+
import { IMAGE_TO_DESIGN_PROMPT } from '@charisol/plexo-sdk/v2/files';
|
|
587
|
+
const r = await fetch('https://api.anthropic.com/v1/messages', {
|
|
588
|
+
method: 'POST',
|
|
589
|
+
headers: { 'content-type': 'application/json', 'x-api-key': process.env.ANTHROPIC_API_KEY, 'anthropic-version': '2023-06-01' },
|
|
590
|
+
body: JSON.stringify({
|
|
591
|
+
model: 'claude-sonnet-5-5', max_tokens: 8000,
|
|
592
|
+
system: IMAGE_TO_DESIGN_PROMPT.replaceAll('{width}', String(width)).replaceAll('{height}', String(height)),
|
|
593
|
+
messages: [{ role: 'user', content: [{ type: 'image', source: { type: 'base64', media_type: 'image/jpeg', data } }, { type: 'text', text: 'Describe this picture as the JSON object.' }] }],
|
|
594
|
+
}),
|
|
595
|
+
});
|
|
596
|
+
// …parse the text of the reply as JSON and return it as { spec }. The SDK validates it; you don't have to.
|
|
597
|
+
```
|
|
598
|
+
|
|
599
|
+
**4. Save** — `result.blob` is the finished file in the format they chose; `result.source` is the editable version. Store both:
|
|
600
|
+
|
|
601
|
+
```ts
|
|
602
|
+
async function save(result: FileSaveResult, existingId?: string) {
|
|
603
|
+
const body = new FormData();
|
|
604
|
+
body.append('file', result.blob, result.filename); // upload this (S3, disk, …)
|
|
605
|
+
body.append('source', JSON.stringify(result.source)); // keep this in your database
|
|
606
|
+
body.append('meta', JSON.stringify({ id: existingId, name: result.name, kind: result.kind, format: result.format }));
|
|
607
|
+
const res = await fetch('/api/files', { method: 'POST', body });
|
|
608
|
+
if (!res.ok) throw new Error('Saving failed. Please try again.'); // shown to the person; they can retry
|
|
609
|
+
}
|
|
610
|
+
|
|
611
|
+
// Reopen later: fetch the stored source and pass it back
|
|
612
|
+
<V2Editor mode="file" files={{ file: storedSource, defaultSaveFormat: row.format, showTypeSwitcher: false, onSaveFile: … }} />
|
|
613
|
+
```
|
|
614
|
+
|
|
615
|
+
A few things worth knowing when you build the real thing:
|
|
616
|
+
- **Errors are for people.** Whatever `uploadPicture`, `imageAi` or `onSaveFile` throws is shown as its message, so write them as plain sentences. A failed AI call never blocks anything: the picture is placed on the canvas and they carry on.
|
|
617
|
+
- **Large files:** `result.blob` can be several MB (a 2x PNG of a long page, a many-page PDF). Send it as multipart (as above) or upload straight to storage with a presigned URL; don't base64 it into JSON.
|
|
618
|
+
- **Pictures hosted elsewhere** must allow cross-origin reading (CORS) to be included in PNG/PDF exports; the person gets a warning when one can't be. Pictures you store with `onUpload` are fine if served from your own origin.
|
|
619
|
+
- **Reopening is lossless** because `source` is the editor's own data (page JSON, HTML, text, or cells), not the exported file. Don't reopen a saved PNG/PDF to edit it: store `source` next to it.
|
|
620
|
+
- **Security:** treat what you load as untrusted if people can share files: HTML files run in a sandbox with scripts off, and the AI answer is validated by the SDK before it is used.
|
|
621
|
+
|
|
322
622
|
## Framework Notes
|
|
323
623
|
|
|
324
624
|
### Vite
|
|
@@ -363,6 +663,7 @@ const PlexoBuilder = lazy(() =>
|
|
|
363
663
|
- Every row/column/element wrapper now carries a `data-plexo-node-type="row"|"column"|"element"` attribute alongside its existing `id` (already the node's stable JSON id).
|
|
364
664
|
|
|
365
665
|
### Unreleased
|
|
666
|
+
- **File editor & export (v2):** `mode="file"` / `"hybrid"`; Figma-style PNG / JPG / PDF / SVG export from the canvas; HTML files with a code editor and live preview; PDF editing; AI picture-to-design; host-driven screens (`files.kind`, `files.file`, `startScreen`, `showTypeSwitcher`, a ref); new entry `@charisol/plexo-sdk/v2/files`; new compile option `nodeIds`; new `features.exportMenu`. New dependencies: `pdfjs-dist` and CodeMirror (both loaded only when used).
|
|
366
667
|
- **Breaking:** Removed the `aiApiKey` prop. AI generation now runs server-side — your provider key is configured once against your Plexo account (encrypted at rest) instead of being passed to the browser on every render.
|
|
367
668
|
- **Breaking:** `TemplateJSON.body.aiConfig` no longer accepts `apiKey`/`provider` — only `useAi`/`tier` remain, for the same reason (a template's JSON is loaded client-side, so it can't hold a secret safely).
|
|
368
669
|
- `aiProvider` is now display/label-only; the effective provider comes from your account configuration, not this prop.
|