@twip/web 0.0.0-canary-d060d80 → 0.0.0-canary-8a13ac8

package/dist/commands.d.ts

@@ -1,5 +1,5 @@
 import type { RichText } from './review.js';
-import type { ControlKind, ControlOptions, DataBinding, ReferenceRule } from './services/elements.js';
+import type { ControlKind, ControlOptions, DataBinding, PlaceholderImage, ReferenceRule } from './services/elements.js';
 import type { TabAlignment, TabLeader, TabSelector } from './services/ruler.js';
 import type { ViewOptions } from './services/view.js';
 import type { AutoCorrectChange, HighlightColor, HorizontalPosition, LineSpacing, MarkupView, ObjectWrap, RowHeight, TablePosition, TableWidth, UnderlineStyle, VerticalPosition, WrapSide } from './state.js';
@@ -9,26 +9,6 @@ export interface FieldTargets {
     /** The fields; default: the selection's. */
     ids?: ElementId[];
 }
-/** How a picture placeholder looks before it is filled. */
-export interface PlaceholderLook {
-    /** Which placeholders: one, those with a tag or a key prefix, or the default for the rest. */
-    match: {
-        id: ElementId;
-    } | {
-        tag: string;
-    } | {
-        prefix: string;
-    } | 'default';
-    /** A fill, label and icon, or an image. */
-    look: {
-        fill?: Color;
-        label?: string;
-        iconSvg?: string;
-    } | {
-        image: Uint8Array;
-        mime: string;
-    };
-}
 /**
  * Every edit, one method per command. Each resolves after its change commits, with `getState()` already at that
  * revision, and rejects with `EditorError`. Commands act on the selection at the time they run. Each is one undo
@@ -501,11 +481,15 @@ export interface Commands {
     }): Promise<void>;
     /** Back to the template from a sub-template, at the template's selection from before. View. */
     closeSubTemplate(): Promise<void>;
-    /** A new sub-template, empty or with a DOCX's body (`category`: default the first rule's). */
+    /**
+     * A new sub-template, empty, with a DOCX's body, or a copy of the sub-template `copyOf` in the same category
+     * (`category`: default the first rule's).
+     */
     createSubTemplate(options: {
         name: string;
         category?: string;
         from?: Uint8Array;
+        copyOf?: string;
     }): Promise<void>;
     /** Renames a sub-template, and with `updateReferences` every reference to it. */
     renameSubTemplate(options: {
@@ -519,6 +503,13 @@ export interface Commands {
         name: string;
         category?: string;
     }): Promise<void>;
+    /**
+     * The template's body becomes the DOCX `from`'s body, on its last section's page; its sub-templates, custom XML
+     * data parts, settings, styles, headers and footers stay. Closes a sub-template being edited first.
+     */
+    replaceBody(options: {
+        from: Uint8Array;
+    }): Promise<void>;
     /** Inserts a content control, optionally around the selection. */
     insertControl(options: {
         kind: ControlKind;
@@ -528,11 +519,20 @@ export interface Commands {
         placeholder?: string;
         binding?: DataBinding;
         options?: ControlOptions;
+        /**
+         * A picture control's placeholder picture (PNG, JPEG, GIF, BMP or SVG): what the editor, the saved DOCX and a
+         * PDF show until it is filled. An SVG is drawn with the picture's box as its viewport, so one with percentage
+         * geometry and no `viewBox` adapts to every size. Default: the engine's.
+         */
+        placeholderImage?: PlaceholderImage;
         wrapSelection?: boolean;
     }): Promise<{
         id: ElementId;
     }>;
-    /** Changes a content control; a `null` binding removes it. */
+    /**
+     * Changes a content control; a `null` binding removes it. `placeholderImage` replaces a picture control's
+     * placeholder picture while it shows it (else it rejects with `unavailable`).
+     */
     setControl(options: {
         id: ElementId;
         tag?: string;
@@ -541,6 +541,7 @@ export interface Commands {
         placeholder?: string;
         binding?: DataBinding | null;
         options?: ControlOptions;
+        placeholderImage?: PlaceholderImage;
     }): Promise<void>;
     /** Removes a content control, optionally keeping its content. */
     removeControl(options: {
@@ -587,11 +588,6 @@ export interface Commands {
         }[];
         clear?: boolean;
     }): Promise<void>;
-    /** Sets how picture placeholders look. View. */
-    setPlaceholderLooks(options: {
-        looks: PlaceholderLook[];
-        merge?: boolean;
-    }): Promise<void>;
     /** Fills the selected placeholder, or every unfilled one with `key`: each becomes a plain picture, its content control removed. */
     fillPlaceholder(options: {
         key?: string;

package/dist/commands.js

@@ -151,6 +151,7 @@ const encodings = {
     createSubTemplate: 'spread',
     renameSubTemplate: 'spread',
     removeSubTemplate: 'spread',
+    replaceBody: 'spread',
     insertControl: 'spread',
     setControl: 'spread',
     removeControl: 'spread',
@@ -160,7 +161,6 @@ const encodings = {
     removeElement: 'value',
     replaceInElements: 'spread',
     markElements: 'spread',
-    setPlaceholderLooks: 'spread',
     fillPlaceholder: 'spread',
     writeDataPart: 'spread',
     removeDataPart: 'spread',

package/dist/editor.d.ts

@@ -192,8 +192,9 @@ export declare class HeadlessEditor {
     /** Replaces the document with a blank one. */
     newDocument(): Promise<void>;
     /**
-     * Exports the document as DOCX or PDF, with the revision it captures. A PDF can take an open password and keywords;
-     * an empty password rejects with `invalid-argument`.
+     * Exports the document as DOCX or PDF, with the revision it captures: the whole document, template and every
+     * sub-template, whether or not a sub-template is being edited. A PDF can take an open password and keywords; an
+     * empty password rejects with `invalid-argument`.
      */
     export(options: ExportOptions): Promise<ExportResult>;
     /** Runs several commands atomically: one transaction and one undo step, or nothing when one fails. */

package/dist/editor.js

@@ -329,8 +329,9 @@ export class HeadlessEditor {
         return sessionOf(this).call(Method.NewDocument);
     }
     /**
-     * Exports the document as DOCX or PDF, with the revision it captures. A PDF can take an open password and keywords;
-     * an empty password rejects with `invalid-argument`.
+     * Exports the document as DOCX or PDF, with the revision it captures: the whole document, template and every
+     * sub-template, whether or not a sub-template is being edited. A PDF can take an open password and keywords; an
+     * empty password rejects with `invalid-argument`.
      */
     export(options) {
         const s = sessionOf(this);

package/dist/index.d.ts

@@ -7,7 +7,7 @@
 export { Editor, HeadlessEditor } from './editor.js';
 export { configure } from './transport/module.js';
 export type { ExportOptions, ExportResult, MountOptions, PdfOptions, SessionOptions } from './editor.js';
-export type { CommandEntry, CommandId, CommandInfo, Commands, FieldTargets, NoArgumentCommandId, Op, OpArgs, PlaceholderLook, } from './commands.js';
+export type { CommandEntry, CommandId, CommandInfo, Commands, FieldTargets, NoArgumentCommandId, Op, OpArgs, } from './commands.js';
 export type { AutoCorrectChange, AutoCorrectEntry, AutoCorrectOptions, CharacterFormatting, CommandState, CommandValues, EditingTarget, EditorState, ElementContext, HighlightColor, HorizontalPosition, HorizontalReference, LineSpacing, MarkupView, Mixed, ObjectHorizontalAlignment, ObjectPlacement, ObjectSelection, ObjectVerticalAlignment, ObjectWrap, PageFormatting, ParagraphFormatting, ReviewState, RowHeight, SelectionSummary, TablePosition, TableSelection, TableStyleOptions, TableWidth, TextDistance, Tri, UnderlineStyle, VerticalPosition, VerticalReference, ViewState, WrapSide, } from './state.js';
 export type { HostCommand, Tooltip, TransactionRecord, TwipEvents } from './events.js';
 export { EditorError } from './errors.js';
@@ -19,7 +19,7 @@ export type { ContextMenu, ContextMenuEvent, MenuAction, MenuItem, MenuTarget, M
 export type { AccessibilityDialogSession, DialogKind, DialogSession, DialogSessionOf, DialogValues, Dialogs, FieldInfo, } from './services/dialogs.js';
 export type { Find, FindMatch, FindQuery, FindResult } from './services/find.js';
 export type { Dictionary, Spelling } from './services/spelling.js';
-export type { Block, ControlKind, ControlOptions, DataBinding, DataParts, ElementDetail, ElementInfo, Elements, MountedElements, PlaceholderInfo, ReferenceResolution, ReferenceRule, SubTemplateInfo, SubTemplateReference, SubTemplates, } from './services/elements.js';
+export type { Block, ControlKind, ControlOptions, PlaceholderImage, DataBinding, DataParts, ElementDetail, ElementInfo, Elements, MountedElements, PlaceholderInfo, ReferenceResolution, ReferenceRule, SubTemplateInfo, SubTemplateReference, SubTemplates, } from './services/elements.js';
 export type { Accessibility, AccessibleId, AccessibleNode, AnnouncementKind, CellPlace, ListPosition, Shortcuts } from './services/accessibility.js';
 export type { Heading, Navigation, StyleInfo, Styles } from './services/navigation.js';
 export type { Ruler, RulerModel, RulerModelSource, RulerUnit, RulerView, TabAlignment, TabLeader, TabSelector, } from './services/ruler.js';

package/dist/services/elements.d.ts

@@ -1,7 +1,7 @@
 import type { Op } from '../commands.js';
 import type { Session } from '../editor.js';
 import type { SelectionSummary } from '../state.js';
-import type { ClientPoint, ElementId } from '../types.js';
+import type { ClientPoint, ElementId, Points } from '../types.js';
 /** A content control's kind. */
 export type ControlKind = 'richText' | 'plainText' | 'picture' | 'checkbox' | 'date' | 'dropDown' | 'comboBox' | 'group' | 'repeatingSection';
 /** The merge designer's elements: fields and content controls. Changing them is done with the commands. */
@@ -76,6 +76,11 @@ export interface ElementInfo {
     locked: boolean;
     /** A sub-template reference field's sub-template. */
     reference?: SubTemplateReference;
+    /** A picture control's picture size (inline or floating). */
+    size?: {
+        width: Points;
+        height: Points;
+    };
 }
 /**
  * One sub-template reference rule (`setSubTemplateRules`): a field of type `fieldType` names, in argument `argument`,
@@ -126,7 +131,17 @@ export interface DataBinding {
     /** The XPath's namespace prefixes. */
     prefixMappings?: string;
 }
-/** A content control's options, by kind: checkbox, date, list, or plain text. */
+/** A picture control's placeholder picture: PNG, JPEG, GIF, BMP or SVG (`image/svg+xml`). */
+export interface PlaceholderImage {
+    /** The picture's bytes. */
+    data: Uint8Array;
+    /** Its MIME type; the data must be one. */
+    mime: string;
+}
+/**
+ * A content control's options, by kind: checkbox, date, list, plain text, or picture. A picture's size (1…1584 pt) is
+ * its placeholder's, and the picture's once filled (fitted to it); `setControl` keeps a side not given.
+ */
 export type ControlOptions = {
     checked?: boolean;
 } | {
@@ -139,6 +154,9 @@ export type ControlOptions = {
     }[];
 } | {
     multiline?: boolean;
+} | {
+    width?: Points;
+    height?: Points;
 };
 /** A block of the document structure. */
 export type Block = {
@@ -197,11 +215,22 @@ export interface SubTemplates {
     edit(name: string, category?: string): Promise<void>;
     /** Back to the template, at its selection from before. */
     close(): Promise<void>;
-    /** A new sub-template, empty or with the body of the DOCX `from`. One undo step. */
+    /**
+     * A new sub-template: empty, with the body of the DOCX `from`, or a copy of the sub-template `copyOf` in the same
+     * category (its formatting, fields, controls, pictures and references). One undo step.
+     */
     create(name: string, options?: {
         category?: string;
         from?: Uint8Array;
+        copyOf?: string;
     }): Promise<void>;
+    /**
+     * A standalone DOCX of a sub-template's body, with the document's styles, numbering, theme and fonts and without
+     * its headers, footers or other sub-templates; `create(name, { from })` reads it back unchanged.
+     */
+    export(name: string, options?: {
+        category?: string;
+    }): Promise<Uint8Array>;
     /** Renames a sub-template; `updateReferences` renames every reference to it too. One undo step. */
     rename(name: string, to: string, options?: {
         category?: string;

package/dist/services/elements.js

@@ -18,6 +18,10 @@ export function createSubTemplates(s) {
         remove: async (name, options) => {
             await s.run({ type: 'removeSubTemplate', name, ...options });
         },
+        export: async (name, options) => {
+            const docx = await s.call(Method.SubTemplateExport, { name, ...options });
+            return Uint8Array.from(atob(docx), (c) => c.charCodeAt(0));
+        },
     };
 }
 /** The elements over a session. */

package/dist/state.d.ts

@@ -426,6 +426,11 @@ export interface ElementContext {
     tag?: string;
     /** A control's title. */
     title?: string;
+    /** A picture control's picture size (inline or floating). */
+    size?: {
+        width: Points;
+        height: Points;
+    };
 }
 /** The selection's character formatting. */
 export interface CharacterFormatting {

package/dist/transport/protocol.d.ts

@@ -91,6 +91,7 @@ export declare const Method: {
     readonly AccessibleGo: 78;
     readonly HostCaretWindowSelect: 79;
     readonly AnnouncementsSet: 80;
+    readonly SubTemplateExport: 81;
 };
 /** A structured call number. */
 export type Method = (typeof Method)[keyof typeof Method];

package/dist/transport/protocol.js

@@ -83,6 +83,7 @@ export const Method = {
     AccessibleGo: 78,
     HostCaretWindowSelect: 79,
     AnnouncementsSet: 80,
+    SubTemplateExport: 81,
 };
 /** What the engine sends: callback kinds of the C ABI. */
 export const Kind = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twip/web",
-  "version": "0.0.0-canary-d060d80",
+  "version": "0.0.0-canary-8a13ac8",
   "description": "The Twip DOCX editor for the browser and Node: a managed, framework-independent editor over the WebAssembly engine.",
   "type": "module",
   "license": "Apache-2.0",