@charisol/plexo-sdk 2.0.27 → 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.
Files changed (47) hide show
  1. package/README.md +301 -0
  2. package/dist/{InlineColorPicker-BYcOgLVc.js → InlineColorPicker-XesBzRsU.js} +362 -114
  3. package/dist/{v1-Dm9rxrfa.js → blank-BEl6CY5C.js} +4657 -10897
  4. package/dist/brandGuide-Dd4fqVjS.js +33 -0
  5. package/dist/{client-DUSU8g5z.js → client-CWui0-3q.js} +1 -1
  6. package/dist/codeEditor-Cux0ud2j.js +205 -0
  7. package/dist/files-Df6FY0HK.js +2182 -0
  8. package/dist/id-CR6Y8qD6.js +8 -0
  9. package/dist/index.js +12786 -13034
  10. package/dist/{brandGuide-DgoZ7spo.js → lint-CV3DmM0X.js} +78 -109
  11. package/dist/pdfImport-BOev0Pc1.js +262 -0
  12. package/dist/plexo-sdk.css +1 -1
  13. package/dist/v1-Cn7SGvZk.js +6253 -0
  14. package/dist/v2/CanvasEditor.d.ts +25 -0
  15. package/dist/v2/V2Editor.d.ts +15 -20
  16. package/dist/v2/compile/build.d.ts +5 -0
  17. package/dist/v2/components/properties/PropertiesPanel.d.ts +1 -0
  18. package/dist/v2/files/aiPicture.d.ts +85 -0
  19. package/dist/v2/files/build.d.ts +49 -0
  20. package/dist/v2/files/capture.d.ts +52 -0
  21. package/dist/v2/files/convert.d.ts +24 -0
  22. package/dist/v2/files/docx.d.ts +1 -0
  23. package/dist/v2/files/engine.d.ts +2 -0
  24. package/dist/v2/files/export.d.ts +97 -0
  25. package/dist/v2/files/import.d.ts +34 -0
  26. package/dist/v2/files/index.d.ts +16 -0
  27. package/dist/v2/files/pdf.d.ts +15 -0
  28. package/dist/v2/files/pdfImport.d.ts +28 -0
  29. package/dist/v2/files/sheet.d.ts +16 -0
  30. package/dist/v2/files/text.d.ts +8 -0
  31. package/dist/v2/files/types.d.ts +96 -0
  32. package/dist/v2/files/ui/ExportDock.d.ts +11 -0
  33. package/dist/v2/files/ui/ExportMenu.d.ts +5 -0
  34. package/dist/v2/files/ui/ExportPanel.d.ts +17 -0
  35. package/dist/v2/files/ui/FileEditor.d.ts +14 -0
  36. package/dist/v2/files/ui/HtmlWorkbench.d.ts +15 -0
  37. package/dist/v2/files/ui/codeEditor.d.ts +12 -0
  38. package/dist/v2/files/ui/editors.d.ts +28 -0
  39. package/dist/v2/files/vector.d.ts +19 -0
  40. package/dist/v2/files/zip.d.ts +10 -0
  41. package/dist/v2/host/HostContext.d.ts +6 -3
  42. package/dist/v2/index.d.ts +5 -1
  43. package/dist/v2-compile.js +17 -16
  44. package/dist/v2-files.js +3 -0
  45. package/dist/v2-strata.js +2 -2
  46. package/dist/v2.js +5805 -4038
  47. package/package.json +18 -3
@@ -0,0 +1,25 @@
1
+ import React from 'react';
2
+ import { type EditorProviderProps } from './context/EditorContext';
3
+ import { type V2HostConfig } from './host/HostContext';
4
+ import type { PageDefinition } from './types/editor';
5
+ import type { DesignSystem } from './design/types';
6
+ export type V2CanvasEditorProps = Omit<EditorProviderProps, 'children'> & V2HostConfig & {
7
+ className?: string;
8
+ };
9
+ /** Imperative handle, mirroring V1's PlexoBuilderRef. */
10
+ export interface V2EditorRef {
11
+ /** Every page, including edits not yet reported through onChange. */
12
+ getPages: () => PageDefinition[];
13
+ /** The design system as it is now. */
14
+ getDesignSystem: () => DesignSystem;
15
+ /** On-screen rect of a node by id (null if not rendered) — for host UI anchored to the canvas, e.g. comment pins. */
16
+ getNodeRect: (nodeId: string) => DOMRect | null;
17
+ }
18
+ /**
19
+ * The V2 visual editor. With no props it opens a blank page and works offline; pass `pages` to edit
20
+ * an existing design and `onChange`/`onSave` to persist it. Mounted under `.plexo-editor` so the SDK's
21
+ * scoped styles apply and nothing leaks into (or out of) the host page. Fills its container.
22
+ */
23
+ export declare const CanvasEditor: React.ForwardRefExoticComponent<Omit<EditorProviderProps, "children"> & V2HostConfig & {
24
+ className?: string;
25
+ } & React.RefAttributes<V2EditorRef>>;
@@ -1,25 +1,20 @@
1
1
  import React from 'react';
2
- import { type EditorProviderProps } from './context/EditorContext';
3
- import { type V2HostConfig } from './host/HostContext';
4
- import type { PageDefinition } from './types/editor';
5
- import type { DesignSystem } from './design/types';
6
- export type V2EditorProps = Omit<EditorProviderProps, 'children'> & V2HostConfig & {
7
- className?: string;
8
- };
9
- /** Imperative handle, mirroring V1's PlexoBuilderRef. */
10
- export interface V2EditorRef {
11
- /** Every page, including edits not yet reported through onChange. */
12
- getPages: () => PageDefinition[];
13
- /** The design system as it is now. */
14
- getDesignSystem: () => DesignSystem;
15
- /** On-screen rect of a node by id (null if not rendered) — for host UI anchored to the canvas, e.g. comment pins. */
16
- getNodeRect: (nodeId: string) => DOMRect | null;
17
- }
2
+ import { type V2CanvasEditorProps, type V2EditorRef } from './CanvasEditor';
3
+ import type { FileEditorRef } from './files/types';
4
+ export type { V2EditorRef } from './CanvasEditor';
5
+ export type { FileEditorRef } from './files/types';
6
+ export type V2EditorProps = V2CanvasEditorProps;
18
7
  /**
19
- * The V2 visual editor. With no props it opens a blank page and works offline; pass `pages` to edit
20
- * an existing design and `onChange`/`onSave` to persist it. Mounted under `.plexo-editor` so the SDK's
8
+ * The V2 editor. By default (`mode` 'page' or 'email') it is the visual canvas: with no props it opens a blank page and works
9
+ * offline; pass `pages` to edit an existing design and `onChange`/`onSave` to persist it. Mounted under `.plexo-editor` so the SDK's
21
10
  * scoped styles apply and nothing leaks into (or out of) the host page. Fills its container.
11
+ *
12
+ * With `mode="file"` it opens the file editor instead — create or open a design (HTML), document, text, Markdown, spreadsheet or
13
+ * a picture, switch between visual / HTML / text views, preview and export (PNG, JPG, PDF, SVG, …). `mode="hybrid"` is the same with
14
+ * the full page and email builders inside. See `files` in V2HostConfig.
22
15
  */
23
- export declare const V2Editor: React.ForwardRefExoticComponent<Omit<EditorProviderProps, "children"> & V2HostConfig & {
16
+ /** The handle: the canvas methods in page/email mode, the file methods (open, create, getSource, exportAs, save) in file/hybrid mode. */
17
+ export type V2EditorHandle = V2EditorRef & Partial<FileEditorRef>;
18
+ export declare const V2Editor: React.ForwardRefExoticComponent<Omit<import("./context/EditorContext").EditorProviderProps, "children"> & import(".").V2HostConfig & {
24
19
  className?: string;
25
- } & React.RefAttributes<V2EditorRef>>;
20
+ } & React.RefAttributes<V2EditorHandle>>;
@@ -24,6 +24,11 @@ export interface CompileOptions extends FormDestinationConfig {
24
24
  * host chooses to pass — it is not sanitised, so only pass what the site's owner wrote, and add it AFTER `sanitizeV2Html`.
25
25
  */
26
26
  customJs?: string;
27
+ /**
28
+ * Stamps every element with `data-plx-node="<its id in the design>"` so a caller can find an element again in the output
29
+ * (the editor's Export uses this to cut out a selection). Off by default: published pages carry no editor ids.
30
+ */
31
+ nodeIds?: boolean;
27
32
  /**
28
33
  * Where the design system's values go. 'root' (default): on `:where(:root)` at zero specificity, so a hosted brand sheet
29
34
  * (`brandStylesheet`, served by the host and linked from the page) overrides them live without a recompile. 'page': on
@@ -1,2 +1,3 @@
1
1
  import React from 'react';
2
+ /** The right-hand panel: the inspector for whatever is selected, with Export pinned beneath it (like Figma). */
2
3
  export declare const PropertiesPanel: React.FC;
@@ -0,0 +1,85 @@
1
+ /**
2
+ * Rebuilding a picture as an editable design. An AI that can see looks at the picture and describes it as a short list of pieces — text,
3
+ * boxes and photos, each with a position — and this turns that description into real, movable elements. Photos are cut out of the
4
+ * original picture, so nothing is redrawn or invented. The AI call itself is the host's (credits, keys): `plexoImageAi` is the default
5
+ * for the Plexo dashboard, or a host passes its own `onConvertImage`.
6
+ */
7
+ import type { PageDefinition } from '../types/editor';
8
+ import { type StoreImage } from './build';
9
+ import type { ImageToDesignInput } from './types';
10
+ type Align = 'left' | 'center' | 'right';
11
+ export type SpecElement = ({
12
+ type: 'text';
13
+ align?: Align;
14
+ text: string;
15
+ x: number;
16
+ y: number;
17
+ w: number;
18
+ h?: number;
19
+ fontSize: number;
20
+ color?: string;
21
+ bold?: boolean;
22
+ italic?: boolean;
23
+ uppercase?: boolean;
24
+ letterSpacing?: number;
25
+ lineHeight?: number;
26
+ }) | ({
27
+ type: 'shape';
28
+ x: number;
29
+ y: number;
30
+ w: number;
31
+ h: number;
32
+ fill?: string;
33
+ radius?: number;
34
+ borderWidth?: number;
35
+ borderColor?: string;
36
+ shadow?: boolean;
37
+ opacity?: number;
38
+ }) | ({
39
+ type: 'picture';
40
+ x: number;
41
+ y: number;
42
+ w: number;
43
+ h: number;
44
+ radius?: number;
45
+ label?: string;
46
+ });
47
+ export interface ImageSpec {
48
+ width: number;
49
+ height: number;
50
+ background: string;
51
+ elements: SpecElement[];
52
+ }
53
+ /** Checks and tidies what the AI sent (it is untrusted text): keeps only what makes sense, clamps everything to the picture. */
54
+ export declare function parseImageSpec(raw: unknown): ImageSpec | null;
55
+ /** Turns the AI's description into a fixed-size page: boxes and text as real elements, photos cut out of the original. */
56
+ export declare function specToPage(spec: ImageSpec, source: {
57
+ dataUrl: string;
58
+ width: number;
59
+ height: number;
60
+ name: string;
61
+ }, store: StoreImage): Promise<PageDefinition>;
62
+ /** Makes a copy small enough to send (and cheap to read): at most 1600px on the long side, as JPEG. */
63
+ export declare function downscaleForAi(dataUrl: string): Promise<{
64
+ dataUrl: string;
65
+ width: number;
66
+ height: number;
67
+ }>;
68
+ /** How the picture reaches the AI: send the (smaller) picture, get back the description. */
69
+ export type ImageAiTransport = (req: {
70
+ image: string;
71
+ width: number;
72
+ height: number;
73
+ name: string;
74
+ signal?: AbortSignal;
75
+ }) => Promise<unknown>;
76
+ /** The Plexo dashboard's own AI (its credits and keys, nothing to set up). */
77
+ export declare const plexoImageAi: ImageAiTransport;
78
+ /** Picture → editable page, using an AI transport. Throws a plain-words message when the AI's answer can't be used. */
79
+ export declare function convertPictureWithAi(input: ImageToDesignInput, ai: ImageAiTransport, store: StoreImage, signal?: AbortSignal): Promise<PageDefinition[]>;
80
+ /**
81
+ * What to tell a vision model so its answer is the description `parseImageSpec` reads. Plexo's own route keeps an identical copy;
82
+ * a host with its own `imageAi` can send this as the system prompt along with the picture.
83
+ */
84
+ export declare const IMAGE_TO_DESIGN_PROMPT = "You turn a picture of a design (a poster, flyer, web page, social post, slide, screenshot, document page) into a description of its parts, so each part can be rebuilt as an editable element. You are shown ONE picture of exactly {width}x{height} pixels. Measure everything in those pixels, origin at the top-left.\n\nReply with ONLY one JSON object, no markdown, no commentary:\n{\"width\":{width},\"height\":{height},\"background\":\"#rrggbb\",\"elements\":[ ... ]}\n\nElements, listed from the back to the front (things drawn underneath come first):\n- {\"type\":\"shape\",\"x\":0,\"y\":0,\"w\":0,\"h\":0,\"fill\":\"#rrggbb\",\"radius\":0,\"borderWidth\":0,\"borderColor\":\"#rrggbb\",\"shadow\":false,\"opacity\":1} for every plain coloured area: cards, buttons, bars, banners, dividers, circles (radius = half the size), panels. Leave fill out for outline-only boxes.\n- {\"type\":\"text\",\"text\":\"exact words\",\"x\":0,\"y\":0,\"w\":0,\"fontSize\":0,\"color\":\"#rrggbb\",\"bold\":false,\"italic\":false,\"align\":\"left\",\"uppercase\":false,\"lineHeight\":1.25,\"letterSpacing\":0} for every piece of writing. x,y is the top-left of the text block, w its width, fontSize the height of a capital letter times 1.4 (in pixels). Keep a paragraph as ONE element with its own line breaks removed; give a separate element to each heading, label and button caption. Copy the words exactly as written; do not translate or fix them.\n- {\"type\":\"picture\",\"x\":0,\"y\":0,\"w\":0,\"h\":0,\"radius\":0,\"label\":\"what it shows\"} for every photo or illustration or logo, anything that is an image rather than flat colour or writing. It will be cut out of the original, so only give its box.\n\nRules: be exact about positions and sizes; use the real colours you see; do not invent anything that is not in the picture; do not describe text that is inside a \"picture\" box separately; at most 250 elements (group tiny repeated details into one picture); the numbers are plain numbers, never strings.";
85
+ export {};
@@ -0,0 +1,49 @@
1
+ /** Builders for designs made of freely placed pieces (a page of a PDF, a rebuilt picture): fixed-size pages of text, shapes and pictures. */
2
+ import type { DocumentNode, PageDefinition } from '../types/editor';
3
+ /** Stores a picture somewhere it can be linked to (the host's upload, or embedded in the design) and returns its address. */
4
+ export type StoreImage = (file: File) => Promise<string>;
5
+ export interface PlacedText {
6
+ text: string;
7
+ x: number;
8
+ y: number;
9
+ /** Box width in px. */
10
+ w: number;
11
+ fontSize: number;
12
+ color: string;
13
+ bold?: boolean;
14
+ italic?: boolean;
15
+ align?: 'left' | 'center' | 'right';
16
+ family?: string;
17
+ /** Wrap inside `w` (true) or stay on one line however wide it gets (false). */
18
+ wrap?: boolean;
19
+ lineHeight?: number;
20
+ letterSpacing?: number;
21
+ uppercase?: boolean;
22
+ }
23
+ export interface PlacedBox {
24
+ x: number;
25
+ y: number;
26
+ w: number;
27
+ h: number;
28
+ fill?: string;
29
+ radius?: number;
30
+ borderWidth?: number;
31
+ borderColor?: string;
32
+ shadow?: string;
33
+ opacity?: number;
34
+ }
35
+ export declare function textNode(t: PlacedText, name?: string): DocumentNode;
36
+ export declare function boxNode(b: PlacedBox, name?: string): DocumentNode;
37
+ export declare function pictureNode(src: string, b: {
38
+ x: number;
39
+ y: number;
40
+ w: number;
41
+ h: number;
42
+ radius?: number;
43
+ }, opts?: {
44
+ name?: string;
45
+ alt?: string;
46
+ locked?: boolean;
47
+ }): DocumentNode;
48
+ /** A fixed-size page (like a sheet of paper or a poster) whose pieces are placed by position. */
49
+ export declare function fixedPage(name: string, width: number, height: number, children: DocumentNode[], background?: string): PageDefinition;
@@ -0,0 +1,52 @@
1
+ export interface CaptureInput {
2
+ /** A complete HTML document (e.g. `compilePageToHtml(...).document`). */
3
+ document: string;
4
+ /** Layout width in CSS pixels (the screen size the page is drawn for). */
5
+ width: number;
6
+ /** Cut out just these elements (`data-plx-node` ids, see compile option `nodeIds`). Absent → the whole page. */
7
+ nodeIds?: string[];
8
+ /** The input is a whole web page of its own (not a design from the editor): draw all of it, edge to edge, as the browser shows it. */
9
+ fullDocument?: boolean;
10
+ }
11
+ export interface Rect {
12
+ x: number;
13
+ y: number;
14
+ width: number;
15
+ height: number;
16
+ }
17
+ export interface Rendered {
18
+ doc: Document;
19
+ /** The area being exported, in page pixels. */
20
+ crop: Rect;
21
+ /** Elements the picture is made of (the cut-out elements, or the page body). */
22
+ roots: Element[];
23
+ /** All of the page's CSS with fonts and pictures copied inside. */
24
+ css: string;
25
+ /** Carried through from the input (a whole page drawn edge to edge). */
26
+ fullDocument?: boolean;
27
+ warnings: string[];
28
+ }
29
+ /**
30
+ * Google Fonts ships each font as one file per script (Latin, Cyrillic, Greek…), each picked by `unicode-range`. Keep only the
31
+ * files whose range covers a character actually on the page, so an export carries the fonts it needs and not twenty others.
32
+ */
33
+ export declare function pruneFontFaces(css: string, pageText: string): string;
34
+ /** Lays the document out and prepares it for drawing. Call `release()` when finished. */
35
+ export declare function renderDocument(input: CaptureInput): Promise<Rendered & {
36
+ release: () => void;
37
+ }>;
38
+ /** The picture as the browser draws it, wrapped in an SVG. Exact, but the SVG relies on a browser to show it. */
39
+ export declare function embeddedSvg(r: Rendered): string;
40
+ /** A true vector SVG: shapes, text and pictures a design tool can open and edit. */
41
+ export declare function vectorSvg(r: Rendered): {
42
+ svg: string;
43
+ warnings: string[];
44
+ };
45
+ export interface Rasterized {
46
+ canvas: HTMLCanvasElement;
47
+ /** The scale actually used (smaller than asked when the picture would be too big for a browser to make). */
48
+ scale: number;
49
+ warnings: string[];
50
+ }
51
+ export declare function svgToCanvas(svg: string, width: number, height: number, scale: number, background: string | null): Promise<Rasterized>;
52
+ export declare function canvasToBlob(canvas: HTMLCanvasElement, mime: 'image/png' | 'image/jpeg', quality?: number): Promise<Blob>;
@@ -0,0 +1,24 @@
1
+ /** Moving content between file kinds (design ⇄ document ⇄ text ⇄ Markdown ⇄ spreadsheet) and starting blank files. */
2
+ import type { PageDefinition } from '../types/editor';
3
+ import type { DesignSystem } from '../design/types';
4
+ import { type Grid } from './sheet';
5
+ import type { FileKind, FileSource } from './types';
6
+ export type Content = PageDefinition[] | string | Grid;
7
+ export declare const isDesignKind: (k: FileKind) => k is "design" | "email";
8
+ export declare const KIND_LABEL: Record<FileKind, string>;
9
+ export declare const KIND_HINT: Record<FileKind, string>;
10
+ /** What a new HTML file starts with: a small page that shows something straight away, ready to be replaced by a paste. */
11
+ export declare const STARTER_HTML = "<!doctype html>\n<html lang=\"en\">\n<head>\n <meta charset=\"utf-8\">\n <title>My page</title>\n <style>\n body { font-family: system-ui, sans-serif; margin: 0; padding: 48px; background: #f8fafc; color: #0f172a; }\n h1 { margin: 0 0 8px; font-size: 40px; }\n p { margin: 0; color: #475569; font-size: 18px; }\n </style>\n</head>\n<body>\n <h1>Hello</h1>\n <p>Paste your own HTML here, or start typing.</p>\n</body>\n</html>\n";
12
+ export declare const blankContent: (kind: FileKind) => Content;
13
+ export declare const sourceOf: (kind: FileKind, name: string, content: Content) => FileSource;
14
+ /** The markup for the inside of a page — what every other kind is converted through. */
15
+ export declare function bodyHtmlOf(kind: FileKind, content: Content, designSystem?: DesignSystem): string;
16
+ /**
17
+ * Compiled design markup is full of layout wrappers and generated class names. For a document keep only what a reader sees:
18
+ * headings, paragraphs, lists, tables, links and pictures, with no styling hooks.
19
+ */
20
+ export declare function semanticHtml(html: string): string;
21
+ /** Converts content to another kind, keeping as much as that kind can hold. */
22
+ export declare function convertContent(from: FileKind, to: FileKind, content: Content, name: string, designSystem?: DesignSystem): Content;
23
+ /** Would converting lose anything the person made (layout, formatting)? Plain text carries nothing to lose. */
24
+ export declare const isLossy: (from: FileKind, to: FileKind) => boolean;
@@ -0,0 +1 @@
1
+ export declare function buildDocx(html: string, title?: string): Promise<Blob>;
@@ -0,0 +1,2 @@
1
+ /** `@charisol/plexo-sdk/v2/files` — the file engine on its own (no editor UI): export and convert. Browser only. */
2
+ export * from './index';
@@ -0,0 +1,97 @@
1
+ /**
2
+ * One call to export anything the SDK edits — a landing page or email design, a selection of it, a document, plain text,
3
+ * Markdown or a spreadsheet — to PNG, JPEG, PDF, SVG, HTML, TXT, MD, DOCX, CSV or XLSX.
4
+ */
5
+ import type { PageDefinition, ViewportMode } from '../types/editor';
6
+ import type { DesignSystem } from '../design/types';
7
+ import type { CompileOptions } from '../compile/build';
8
+ import { type Grid } from './sheet';
9
+ export type ExportFormat = 'png' | 'jpeg' | 'pdf' | 'svg' | 'html' | 'txt' | 'md' | 'docx' | 'csv' | 'xlsx';
10
+ export declare const EXPORT_FORMATS: Array<{
11
+ id: ExportFormat;
12
+ label: string;
13
+ ext: string;
14
+ mime: string; /** What you get, in plain words. */
15
+ hint: string;
16
+ }>;
17
+ /** The four formats offered for a selection of a design (Figma-style). */
18
+ export declare const PICTURE_FORMATS: ExportFormat[];
19
+ export interface ExportOptions {
20
+ format: ExportFormat;
21
+ /** Picture sharpness for PNG / JPG / PDF (1x, 2x, 3x, 4x). Default 2. */
22
+ scale?: number;
23
+ /** Behind the picture. Default: see-through for PNG, white for JPG and PDF. `null` = see-through. */
24
+ background?: string | null;
25
+ /** JPEG quality 0–1. Default 0.92. */
26
+ quality?: number;
27
+ /** SVG: 'vector' (default — shapes and text a design tool can edit) or 'exact' (the browser's own drawing wrapped in an SVG). */
28
+ svgMode?: 'vector' | 'exact';
29
+ /** PDF: 'single' (default — one long page, like the screen) or 'a4' (split into A4 pages). */
30
+ pdfPaging?: 'single' | 'a4';
31
+ /** File name without the extension. */
32
+ filename?: string;
33
+ /** Add "@2x" (and so on) to a picture's file name when it isn't 1x, like Figma does. Default true; Save in the file editor turns it off. */
34
+ scaleSuffix?: boolean;
35
+ }
36
+ export interface ExportResult {
37
+ blob: Blob;
38
+ /** With extension, e.g. `Home@2x.png`. */
39
+ filename: string;
40
+ mime: string;
41
+ /** Anything the owner should know, in plain words (e.g. a picture that couldn't be included). */
42
+ warnings: string[];
43
+ }
44
+ export type ExportSource = {
45
+ kind: 'design';
46
+ page: PageDefinition;
47
+ /** All the pages of a multi-page file (a PDF, say). PDF export then writes every page; PNG / JPG / SVG give one file per page in a zip. */
48
+ pages?: PageDefinition[];
49
+ designSystem?: DesignSystem;
50
+ /** Which screen to draw. Default 'desktop'. */
51
+ viewport?: ViewportMode;
52
+ /** Export only these elements (their ids in the design). Absent → the whole page. */
53
+ nodeIds?: string[];
54
+ /** Email designs are exported as they will be sent. */
55
+ mode?: 'page' | 'email';
56
+ compile?: Partial<CompileOptions>;
57
+ } | {
58
+ /** A document, text or Markdown, as HTML markup for the inside of a page. */
59
+ kind: 'html';
60
+ name: string;
61
+ body: string;
62
+ css?: string;
63
+ /** Page width in pixels. Default 816 (US Letter at 96 dpi). */
64
+ width?: number;
65
+ /** Draw as a sheet of paper (padding, readable type). Default true. */
66
+ paper?: boolean;
67
+ /** Show the words exactly as typed (monospace, line breaks kept). */
68
+ mono?: boolean;
69
+ } | {
70
+ /** A web page as code (a full document, or just some markup), drawn exactly as the browser shows it. */
71
+ kind: 'rawhtml';
72
+ name: string;
73
+ html: string;
74
+ /** Page width in pixels. Default 1200. */
75
+ width?: number;
76
+ } | {
77
+ kind: 'sheet';
78
+ name: string;
79
+ grid: Grid;
80
+ };
81
+ export declare const DOC_CSS: (mono: boolean, paper: boolean) => string;
82
+ /** A complete, self-contained HTML file around some markup. */
83
+ export declare function wrapHtmlDocument(title: string, body: string, opts?: {
84
+ css?: string;
85
+ mono?: boolean;
86
+ paper?: boolean;
87
+ }): string;
88
+ /** Saves a file to the person's computer. */
89
+ export declare function downloadResult(result: {
90
+ blob: Blob;
91
+ filename: string;
92
+ }): void;
93
+ /**
94
+ * Exports one thing to one format. Works in the browser (it draws pages with the browser's own engine).
95
+ * A design with several `pages` exports every page: one PDF with all of them, or a zip of one picture per page.
96
+ */
97
+ export declare function exportSource(src: ExportSource, opts: ExportOptions): Promise<ExportResult>;
@@ -0,0 +1,34 @@
1
+ /** Opening files: images, HTML, Markdown, text, CSV, Word (.docx) and Excel (.xlsx) become something the editor can edit. */
2
+ import type { PageDefinition } from '../types/editor';
3
+ import { type Grid } from './sheet';
4
+ import type { FileSource } from './types';
5
+ /** Reads the files inside a zip (.docx and .xlsx are zips). */
6
+ export declare function unzip(buf: ArrayBuffer): Promise<Map<string, Uint8Array>>;
7
+ export declare function docxToHtml(buf: ArrayBuffer): Promise<string>;
8
+ export declare function xlsxToGrid(buf: ArrayBuffer): Promise<Grid>;
9
+ /** Turns written content (headings, paragraphs, lists, pictures) into a design the visual canvas can edit. */
10
+ export declare function htmlToDesign(html: string, name?: string): PageDefinition[];
11
+ export declare const markdownToDesign: (md: string, name?: string) => PageDefinition[];
12
+ export declare const textToDesign: (t: string, name?: string) => PageDefinition[];
13
+ /** A picture placed on a canvas the size of the picture, ready to edit (crop, resize, put text over). */
14
+ export declare function imageToDesign(dataUrl: string, width: number, height: number, name?: string): PageDefinition[];
15
+ export declare const loadImageSize: (url: string) => Promise<{
16
+ width: number;
17
+ height: number;
18
+ }>;
19
+ export type Opened = {
20
+ type: 'source';
21
+ source: FileSource;
22
+ } | {
23
+ type: 'pdf';
24
+ name: string;
25
+ read: import('./pdfImport').ReadPdfResult;
26
+ } | {
27
+ type: 'image';
28
+ name: string;
29
+ dataUrl: string;
30
+ width: number;
31
+ height: number;
32
+ };
33
+ /** Works out what a file is and opens it. Throws a plain-words message when it can't be opened. */
34
+ export declare function openFile(file: File | Blob, fallbackName?: string): Promise<Opened>;
@@ -0,0 +1,16 @@
1
+ /**
2
+ * Files: open, convert and export. Everything here runs in the browser (pages are drawn with the browser's own engine) and has no
3
+ * dependencies beyond the SDK. The editor UI is `FileEditor` (or `<V2Editor mode="file" />`).
4
+ */
5
+ export { exportSource, downloadResult, wrapHtmlDocument, EXPORT_FORMATS, PICTURE_FORMATS } from './export';
6
+ export type { ExportFormat, ExportOptions, ExportResult, ExportSource } from './export';
7
+ export { openFile, htmlToDesign, markdownToDesign, textToDesign, imageToDesign, docxToHtml, xlsxToGrid } from './import';
8
+ export type { Opened } from './import';
9
+ export { htmlToText, htmlToMarkdown, markdownToHtml, textToHtml } from './text';
10
+ export { parseCsv, toCsv, evaluateGrid } from './sheet';
11
+ export type { Grid } from './sheet';
12
+ export { convertContent, blankContent, KIND_LABEL } from './convert';
13
+ export type { FileKind, FileSource, FileSaveResult, FileEditorConfig, FileEditorRef, ImageToDesignInput } from './types';
14
+ export { convertPictureWithAi, plexoImageAi, parseImageSpec, specToPage, IMAGE_TO_DESIGN_PROMPT } from './aiPicture';
15
+ export type { ImageSpec, SpecElement, ImageAiTransport } from './aiPicture';
16
+ export { readPdf, pdfToPages } from './pdfImport';
@@ -0,0 +1,15 @@
1
+ /** A minimal PDF writer: each page is one JPEG picture. No dependencies — it is how PNG/JPEG-quality pages become a PDF. */
2
+ export interface PdfPage {
3
+ /** JPEG file bytes. */
4
+ jpeg: Uint8Array;
5
+ /** Picture size in pixels. */
6
+ width: number;
7
+ height: number;
8
+ }
9
+ export declare function jpegsToPdf(pages: PdfPage[], opts?: {
10
+ title?: string;
11
+ pagePx?: Array<{
12
+ width: number;
13
+ height: number;
14
+ }>;
15
+ }): Blob;
@@ -0,0 +1,28 @@
1
+ /**
2
+ * Opening a PDF for editing. Each page is drawn to a picture, the words on it are read out with their positions, and the page becomes a
3
+ * design: the picture (with the words wiped from it) underneath, and the words on top as real, movable, editable text. Scanned PDFs have
4
+ * no words to read, so their pages come back as plain pictures for the AI picture conversion instead.
5
+ *
6
+ * Runs in the browser. The PDF engine (pdf.js) is loaded only when a PDF is opened, so it adds nothing to people who never do.
7
+ */
8
+ import type { PageDefinition } from '../types/editor';
9
+ import { type PlacedText, type StoreImage } from './build';
10
+ export interface PdfPageData {
11
+ /** Page size in CSS pixels (96 dpi). */
12
+ width: number;
13
+ height: number;
14
+ /** The page picture. With the words wiped out when `texts` has any. */
15
+ image: Blob;
16
+ /** Words with positions; empty for a scanned page. */
17
+ texts: PlacedText[];
18
+ /** The page exactly as printed, for AI conversion of a scanned page. */
19
+ original?: Blob;
20
+ }
21
+ export interface ReadPdfResult {
22
+ pages: PdfPageData[];
23
+ /** How many pages the PDF has (more than were read when it is very long). */
24
+ total: number;
25
+ }
26
+ export declare function readPdf(buf: ArrayBuffer): Promise<ReadPdfResult>;
27
+ /** Builds one design page per PDF page: the picture underneath (locked, so it doesn't get dragged by accident), the words on top. */
28
+ export declare function pdfToPages(read: ReadPdfResult, name: string, store: StoreImage): Promise<PageDefinition[]>;
@@ -0,0 +1,16 @@
1
+ export type Grid = string[][];
2
+ export declare const colName: (i: number) => string;
3
+ export declare function parseCsv(text: string, delimiter?: string): Grid;
4
+ export declare function toCsv(grid: Grid, delimiter?: string): string;
5
+ /** Drops the empty rows and columns after the last thing typed, so exports aren't padded with blank grid. Always keeps at least one cell. */
6
+ export declare function trimGrid(grid: Grid): Grid;
7
+ /**
8
+ * Works out every cell of a grid. A cell starting with "=" is a formula: + − × ÷ ( ), cell names (B2), ranges (A1:A9) and
9
+ * SUM / AVERAGE / MIN / MAX / COUNT / ROUND / ABS / SQRT. A formula that can't be worked out shows "#ERROR" instead of breaking the sheet.
10
+ */
11
+ export declare function evaluateGrid(grid: Grid): Grid;
12
+ export declare function gridToHtml(grid: Grid, opts?: {
13
+ header?: boolean;
14
+ }): string;
15
+ export declare function gridToMarkdown(grid: Grid): string;
16
+ export declare function buildXlsx(grid: Grid, sheetName?: string): Blob;
@@ -0,0 +1,8 @@
1
+ /** Plain text ⇄ Markdown ⇄ HTML. Small, dependency-free converters for the file editor (browser only: they read HTML with DOMParser). */
2
+ /** The words on a page, in reading order, with paragraphs separated by a blank line. */
3
+ export declare function htmlToText(html: string): string;
4
+ export declare function htmlToMarkdown(html: string): string;
5
+ /** A readable subset of Markdown: headings, emphasis, links, pictures, lists, quotes, code, rules and tables. */
6
+ export declare function markdownToHtml(md: string): string;
7
+ export declare function textToHtml(text: string): string;
8
+ export declare const escapeHtml: (s: string) => string;
@@ -0,0 +1,96 @@
1
+ import type { PageDefinition } from '../types/editor';
2
+ import type { ExportFormat } from './export';
3
+ /**
4
+ * What kind of file is being made or edited.
5
+ * - design: a page built on the visual canvas (HTML) · email: the same, as an email
6
+ * - document: written text with headings, lists and pictures (Word-style) · text: plain text · markdown
7
+ * - sheet: a spreadsheet grid
8
+ */
9
+ export type FileKind = 'design' | 'email' | 'html' | 'document' | 'text' | 'markdown' | 'sheet';
10
+ /** A file's content in the form the editor works with, so a host can store it and open it again later. */
11
+ export type FileSource = {
12
+ kind: 'design' | 'email';
13
+ name: string;
14
+ content: PageDefinition[];
15
+ } | {
16
+ kind: 'html' | 'document' | 'text' | 'markdown';
17
+ name: string;
18
+ content: string;
19
+ } | {
20
+ kind: 'sheet';
21
+ name: string;
22
+ content: string[][];
23
+ };
24
+ /** What the editor hands the host when the person saves. */
25
+ export interface FileSaveResult {
26
+ kind: FileKind;
27
+ /** The name the person gave it, without extension. */
28
+ name: string;
29
+ /** The format the person chose to save in. */
30
+ format: ExportFormat;
31
+ /** The finished file in that format — upload it or store it. */
32
+ blob: Blob;
33
+ /** `name.ext`, ready to use as a file name. */
34
+ filename: string;
35
+ /** The editable source, so the host can open this file in the editor again (`file={result.source}`). */
36
+ source: FileSource;
37
+ /** Anything worth telling the person (e.g. a picture that couldn't be included). */
38
+ warnings: string[];
39
+ }
40
+ export interface ImageToDesignInput {
41
+ dataUrl: string;
42
+ name: string;
43
+ width: number;
44
+ height: number;
45
+ }
46
+ export interface FileEditorConfig {
47
+ /** Open this file: a File/Blob (an image, .html, .md, .txt, .csv, .docx, .xlsx) or a source the editor gave you earlier. Absent → the person picks what to create. */
48
+ file?: File | Blob | FileSource;
49
+ /** Name to use when `file` is an unnamed Blob. */
50
+ fileName?: string;
51
+ /** Start a new file of this kind. Default: ask, offering Design (HTML) first. */
52
+ kind?: FileKind;
53
+ /** Which kinds to offer. Default: design, document, text, markdown, sheet (plus email in hybrid mode). */
54
+ kinds?: FileKind[];
55
+ /** Formats offered under "Save as". Default: the sensible ones for the kind. */
56
+ saveFormats?: ExportFormat[];
57
+ /** The format the Save button uses until the person picks another (e.g. the format this file was last saved in). Default: the first of `saveFormats`. */
58
+ defaultSaveFormat?: import('./export').ExportFormat;
59
+ /** Called when the person saves — send the file back to your app. Absent → no Save button; Export (a download) is always there. */
60
+ onSaveFile?: (result: FileSaveResult) => void | Promise<void>;
61
+ /** The back/close button. Absent → no back button. */
62
+ onClose?: () => void;
63
+ /**
64
+ * Rebuild a picture as an editable design (text as text, boxes as boxes, photos cut out). Inside the Plexo dashboard
65
+ * (`apiKey="workspace-internal"`) this is built in and uses the account's AI credits, so there is nothing to pass. Elsewhere, pass your
66
+ * own: either a full replacement that returns pages, or — simpler — `imageAi`, which only has to send the picture to a vision model and
67
+ * return its JSON description (see `IMAGE_TO_DESIGN_PROMPT`). With neither, a picture is placed on the canvas as one image.
68
+ */
69
+ onConvertImage?: (image: ImageToDesignInput) => Promise<PageDefinition[]>;
70
+ imageAi?: import('./aiPicture').ImageAiTransport;
71
+ /** Turn the built-in AI picture conversion off (a picture is then just placed on the canvas). */
72
+ aiConversion?: boolean;
73
+ /**
74
+ * Show the Design | HTML | Document… switch at the top, so the person can change what they are making. Default true. Set false when
75
+ * your own screen decides the type and it shouldn't change (the file's type is then fixed to `kind` / the opened file).
76
+ */
77
+ showTypeSwitcher?: boolean;
78
+ /**
79
+ * Our "What would you like to make?" screen, shown when neither `file` nor `kind` is given. Default true. Set false to use your own
80
+ * chooser: with nothing given the editor then opens a new file of the first of `kinds` instead of asking.
81
+ */
82
+ startScreen?: boolean;
83
+ }
84
+ /** Drive the file editor from the host's own screens (`ref` on `<V2Editor mode="file">` or `<FileEditor>`). */
85
+ export interface FileEditorRef {
86
+ /** Open a file (File/Blob of any supported type, or a source saved before), replacing what is open. */
87
+ open: (file: File | Blob | FileSource) => Promise<void>;
88
+ /** Start a new, empty file of this kind, replacing what is open. */
89
+ create: (kind: FileKind, name?: string) => void;
90
+ /** What is open now, as a source the host can store and reopen (null before anything is open). */
91
+ getSource: () => FileSource | null;
92
+ /** Make the finished file in a format without saving it anywhere (to upload or download it yourself). */
93
+ exportAs: (format: import('./export').ExportFormat, opts?: Omit<import('./export').ExportOptions, 'format'>) => Promise<import('./export').ExportResult>;
94
+ /** Save in a format through `onSaveFile` (the first of the offered formats when omitted). */
95
+ save: (format?: import('./export').ExportFormat) => Promise<void>;
96
+ }
@@ -0,0 +1,11 @@
1
+ import React from 'react';
2
+ import type { ExportSource } from '../export';
3
+ /** What the Export controls will export right now: the selection, or the whole page when nothing (or only the page) is selected. */
4
+ export declare function useExportTarget(): {
5
+ nodeIds: string[];
6
+ name: string;
7
+ note: string;
8
+ getSource: () => ExportSource;
9
+ };
10
+ /** The Export section pinned to the bottom of the right-hand panel, like Figma's. Opens with ⇧⌘E. */
11
+ export declare const ExportDock: React.FC;