@digital-gravy/etch-public-api 0.7.1 → 0.7.2

package/dist/index.d.cts

@@ -265,6 +265,50 @@ interface BlockPatch {
     /** Replace the text content. Only valid on text blocks. */
     text?: string;
 }
+/**
+ * A portable, JSON-serializable snapshot of a block subtree produced by
+ * {@link EtchBlocksApi.copy} and consumed by {@link EtchBlocksApi.pasteAsync}.
+ *
+ * Treat it as an **opaque token**: store it, send it over the wire, or hand it
+ * straight back to `pasteAsync()`. The fields below are documented so you can
+ * inspect a payload, but the bundled `styles` / `loops` / `components` /
+ * `customMediaDefinitions` are Etch-internal definitions that `pasteAsync()`
+ * re-creates and re-maps to fresh ids — don't depend on their internal shape or
+ * mutate them.
+ *
+ * Unlike the builder's Cmd-C / Cmd-V shortcuts, `copy()` / `pasteAsync()` never
+ * touch the system clipboard, so they work for fully programmatic flows (no
+ * user gesture or clipboard permission required).
+ */
+interface CopyObject {
+    /** Payload kind. Currently always `"block"`. */
+    type: 'block';
+    /**
+     * Payload schema version, derived from the features the copied block uses.
+     * `paste()` migrates older payloads forward, so pass it back unchanged.
+     */
+    version: number;
+    /** The copied block subtree in Gutenberg block grammar. */
+    gutenbergBlock: GutenbergBlock;
+    /** Global styles referenced by the block, keyed by style id (opaque). */
+    styles?: {
+        [styleId: string]: unknown;
+    };
+    /** Loop definitions referenced by the block, keyed by loop id (opaque). */
+    loops?: {
+        [loopId: string]: unknown;
+    };
+    /** Component definitions referenced by the block, keyed by component id (opaque). */
+    components?: {
+        [componentId: number]: unknown;
+    };
+    /** `@custom-media` definitions referenced by the block's styles (opaque). */
+    customMediaDefinitions?: {
+        [name: string]: unknown;
+    };
+    /** ISO 8601 timestamp of when the copy was produced. */
+    timestamp?: string;
+}
 /** Block selection, reading, structure and property edits. */
 interface EtchBlocksApi {
     /** Select a block in the canvas by id. */
@@ -281,9 +325,10 @@ interface EtchBlocksApi {
     find(predicate: FindBlocksPredicate): string[];
     /**
      * Build a block from JSON and insert it; returns the new block id.
-     * `parentId` defaults to the document root, `index` to the end of the parent.
+     * `parentId` defaults to the document root (`null` is treated the same as
+     * omitting it, matching {@link move}), `index` to the end of the parent.
      */
-    create(json: EtchBlockJson, parentId?: string, index?: number): string;
+    create(json: EtchBlockJson, parentId?: string | null, index?: number): string;
     /** Remove a block and its entire subtree. */
     delete(blockId: string): void;
     /** Deep-copy a block next to the original; returns the new block's id. */
@@ -297,6 +342,32 @@ interface EtchBlocksApi {
     replace(blockId: string, json: EtchBlockJson): string;
     /** Patch a block's common editable properties in place (keeps id/children). */
     update(blockId: string, patch: BlockPatch): void;
+    /**
+     * Serialize a block and its subtree — along with the global styles, loops and
+     * components it references — into a portable {@link CopyObject}. The result is
+     * plain JSON: hold it, persist it, or pass it to {@link pasteAsync}. Unlike the
+     * Cmd-C shortcut this does **not** write to the system clipboard. Throws
+     * `BLOCK_NOT_FOUND` for an unknown id.
+     */
+    copy(blockId: string): CopyObject;
+    /**
+     * Insert a block previously produced by {@link copy}. Any styles, loops and
+     * components it carries are re-created and re-mapped to fresh ids. Resolves to
+     * the id of the newly inserted block. Throws `INVALID_ARGUMENT` for a
+     * malformed payload and `BLOCK_NOT_FOUND` for an unknown `targetId`.
+     *
+     * Placement (mirrors {@link create}):
+     * - **No `targetId`** (omitted or `null`) — appended to the document root, or
+     *   inserted there at `index` when given.
+     * - **`targetId` + `index`** — inserted as a child of the target at `index`.
+     * - **`targetId`, no `index`** — inserted into the target when it accepts
+     *   children, otherwise immediately after it (handy for "paste near this
+     *   block").
+     *
+     * `index` is clamped to the valid range; a negative `index` counts from the
+     * end (`-1` appends).
+     */
+    pasteAsync(payload: CopyObject, targetId?: string | null, index?: number): Promise<string>;
     /** Set the text content of a text block. */
     setText(blockId: string, text: string): void;
     /** Rename a block (sets its label / display name). */
@@ -1352,4 +1423,4 @@ declare function isEtchApiError(value: unknown): value is EtchApiError;
  */
 declare const ETCH_API_VERSION = "0.x";
 
-export { type ArrayComponentProperty, type BlockLoopBinding, type BlockPatch, type BooleanComponentProperty, type BooleanParam, type BridgeConnectOptions, type ClassComponentProperty, type ColorScheme, type ComponentPatch, type ComponentProperty, type ComponentPropertyBase, type ConditionComponentProperty, type ConnectOptions, type CustomField, type CustomFieldAssignment, type CustomFieldGroup, type CustomFieldType, ETCH_API_VERSION, type Etch, EtchApiError, type EtchApiErrorCode, type EtchBlockCommon, type EtchBlockContext, type EtchBlockJson, type EtchBlockOptions, type EtchBlockScript, type EtchBlockType, type EtchBlockTypeName, type EtchBlocksApi, type EtchBridgeConnection, type EtchComponentBlockJson, type EtchComponentsApi, type EtchConditionBlockJson, type EtchDynamicElementBlockJson, type EtchDynamicImageBlockJson, type EtchElementBlockJson, type EtchFieldsApi, type EtchHistoryApi, type EtchHtmlAttributes, type EtchLoop, type EtchLoopBlockJson, type EtchLoopConfig, type EtchLoopObj, type EtchLoopsApi, type EtchNavigationApi, type EtchPassthroughBlockJson, type EtchPostContentBlockJson, type EtchRawHtmlBlockJson, type EtchSlotContentBlockJson, type EtchSlotPlaceholderBlockJson, type EtchStylesApi, type EtchStylesheetsApi, type EtchSvgBlockJson, type EtchTextBlockJson, type EtchUiApi, type FindBlocksPredicate, type GroupComponentProperty, type GutenbergBlock, type LoopParamRef, type MetaQueryItem, type NavigationPlace, type NumberComponentProperty, type NumericParam, type ObjectComponentProperty, type PostCustomFieldGroupEntry, type PostCustomFieldValueEntry, type PostCustomFieldValueResponse, type PostCustomFieldValuesResponse, type PostSummary, type PublicBlockJson, type PublicComponentJson, type PublicComponentSummary, type RepeaterComponentProperty, type ResolvedCustomField, type SelectOptionsString, type StringComponentProperty, type StyleListFilter, type StylePatch, type StyleSelectorType, type StyleSummary, type StylesheetInput, type StylesheetPatch, type StylesheetSummary, type StylesheetType, type TaxQueryItem, type TemplateSummary, type WpQueryArgs, type WpTermsArgs, type WpUsersArgs, getEtch, isEtchApiError, isEtchAvailable };
+export { type ArrayComponentProperty, type BlockLoopBinding, type BlockPatch, type BooleanComponentProperty, type BooleanParam, type BridgeConnectOptions, type ClassComponentProperty, type ColorScheme, type ComponentPatch, type ComponentProperty, type ComponentPropertyBase, type ConditionComponentProperty, type ConnectOptions, type CopyObject, type CustomField, type CustomFieldAssignment, type CustomFieldGroup, type CustomFieldType, ETCH_API_VERSION, type Etch, EtchApiError, type EtchApiErrorCode, type EtchBlockCommon, type EtchBlockContext, type EtchBlockJson, type EtchBlockOptions, type EtchBlockScript, type EtchBlockType, type EtchBlockTypeName, type EtchBlocksApi, type EtchBridgeConnection, type EtchComponentBlockJson, type EtchComponentsApi, type EtchConditionBlockJson, type EtchDynamicElementBlockJson, type EtchDynamicImageBlockJson, type EtchElementBlockJson, type EtchFieldsApi, type EtchHistoryApi, type EtchHtmlAttributes, type EtchLoop, type EtchLoopBlockJson, type EtchLoopConfig, type EtchLoopObj, type EtchLoopsApi, type EtchNavigationApi, type EtchPassthroughBlockJson, type EtchPostContentBlockJson, type EtchRawHtmlBlockJson, type EtchSlotContentBlockJson, type EtchSlotPlaceholderBlockJson, type EtchStylesApi, type EtchStylesheetsApi, type EtchSvgBlockJson, type EtchTextBlockJson, type EtchUiApi, type FindBlocksPredicate, type GroupComponentProperty, type GutenbergBlock, type LoopParamRef, type MetaQueryItem, type NavigationPlace, type NumberComponentProperty, type NumericParam, type ObjectComponentProperty, type PostCustomFieldGroupEntry, type PostCustomFieldValueEntry, type PostCustomFieldValueResponse, type PostCustomFieldValuesResponse, type PostSummary, type PublicBlockJson, type PublicComponentJson, type PublicComponentSummary, type RepeaterComponentProperty, type ResolvedCustomField, type SelectOptionsString, type StringComponentProperty, type StyleListFilter, type StylePatch, type StyleSelectorType, type StyleSummary, type StylesheetInput, type StylesheetPatch, type StylesheetSummary, type StylesheetType, type TaxQueryItem, type TemplateSummary, type WpQueryArgs, type WpTermsArgs, type WpUsersArgs, getEtch, isEtchApiError, isEtchAvailable };

package/dist/index.d.ts

@@ -265,6 +265,50 @@ interface BlockPatch {
     /** Replace the text content. Only valid on text blocks. */
     text?: string;
 }
+/**
+ * A portable, JSON-serializable snapshot of a block subtree produced by
+ * {@link EtchBlocksApi.copy} and consumed by {@link EtchBlocksApi.pasteAsync}.
+ *
+ * Treat it as an **opaque token**: store it, send it over the wire, or hand it
+ * straight back to `pasteAsync()`. The fields below are documented so you can
+ * inspect a payload, but the bundled `styles` / `loops` / `components` /
+ * `customMediaDefinitions` are Etch-internal definitions that `pasteAsync()`
+ * re-creates and re-maps to fresh ids — don't depend on their internal shape or
+ * mutate them.
+ *
+ * Unlike the builder's Cmd-C / Cmd-V shortcuts, `copy()` / `pasteAsync()` never
+ * touch the system clipboard, so they work for fully programmatic flows (no
+ * user gesture or clipboard permission required).
+ */
+interface CopyObject {
+    /** Payload kind. Currently always `"block"`. */
+    type: 'block';
+    /**
+     * Payload schema version, derived from the features the copied block uses.
+     * `paste()` migrates older payloads forward, so pass it back unchanged.
+     */
+    version: number;
+    /** The copied block subtree in Gutenberg block grammar. */
+    gutenbergBlock: GutenbergBlock;
+    /** Global styles referenced by the block, keyed by style id (opaque). */
+    styles?: {
+        [styleId: string]: unknown;
+    };
+    /** Loop definitions referenced by the block, keyed by loop id (opaque). */
+    loops?: {
+        [loopId: string]: unknown;
+    };
+    /** Component definitions referenced by the block, keyed by component id (opaque). */
+    components?: {
+        [componentId: number]: unknown;
+    };
+    /** `@custom-media` definitions referenced by the block's styles (opaque). */
+    customMediaDefinitions?: {
+        [name: string]: unknown;
+    };
+    /** ISO 8601 timestamp of when the copy was produced. */
+    timestamp?: string;
+}
 /** Block selection, reading, structure and property edits. */
 interface EtchBlocksApi {
     /** Select a block in the canvas by id. */
@@ -281,9 +325,10 @@ interface EtchBlocksApi {
     find(predicate: FindBlocksPredicate): string[];
     /**
      * Build a block from JSON and insert it; returns the new block id.
-     * `parentId` defaults to the document root, `index` to the end of the parent.
+     * `parentId` defaults to the document root (`null` is treated the same as
+     * omitting it, matching {@link move}), `index` to the end of the parent.
      */
-    create(json: EtchBlockJson, parentId?: string, index?: number): string;
+    create(json: EtchBlockJson, parentId?: string | null, index?: number): string;
     /** Remove a block and its entire subtree. */
     delete(blockId: string): void;
     /** Deep-copy a block next to the original; returns the new block's id. */
@@ -297,6 +342,32 @@ interface EtchBlocksApi {
     replace(blockId: string, json: EtchBlockJson): string;
     /** Patch a block's common editable properties in place (keeps id/children). */
     update(blockId: string, patch: BlockPatch): void;
+    /**
+     * Serialize a block and its subtree — along with the global styles, loops and
+     * components it references — into a portable {@link CopyObject}. The result is
+     * plain JSON: hold it, persist it, or pass it to {@link pasteAsync}. Unlike the
+     * Cmd-C shortcut this does **not** write to the system clipboard. Throws
+     * `BLOCK_NOT_FOUND` for an unknown id.
+     */
+    copy(blockId: string): CopyObject;
+    /**
+     * Insert a block previously produced by {@link copy}. Any styles, loops and
+     * components it carries are re-created and re-mapped to fresh ids. Resolves to
+     * the id of the newly inserted block. Throws `INVALID_ARGUMENT` for a
+     * malformed payload and `BLOCK_NOT_FOUND` for an unknown `targetId`.
+     *
+     * Placement (mirrors {@link create}):
+     * - **No `targetId`** (omitted or `null`) — appended to the document root, or
+     *   inserted there at `index` when given.
+     * - **`targetId` + `index`** — inserted as a child of the target at `index`.
+     * - **`targetId`, no `index`** — inserted into the target when it accepts
+     *   children, otherwise immediately after it (handy for "paste near this
+     *   block").
+     *
+     * `index` is clamped to the valid range; a negative `index` counts from the
+     * end (`-1` appends).
+     */
+    pasteAsync(payload: CopyObject, targetId?: string | null, index?: number): Promise<string>;
     /** Set the text content of a text block. */
     setText(blockId: string, text: string): void;
     /** Rename a block (sets its label / display name). */
@@ -1352,4 +1423,4 @@ declare function isEtchApiError(value: unknown): value is EtchApiError;
  */
 declare const ETCH_API_VERSION = "0.x";
 
-export { type ArrayComponentProperty, type BlockLoopBinding, type BlockPatch, type BooleanComponentProperty, type BooleanParam, type BridgeConnectOptions, type ClassComponentProperty, type ColorScheme, type ComponentPatch, type ComponentProperty, type ComponentPropertyBase, type ConditionComponentProperty, type ConnectOptions, type CustomField, type CustomFieldAssignment, type CustomFieldGroup, type CustomFieldType, ETCH_API_VERSION, type Etch, EtchApiError, type EtchApiErrorCode, type EtchBlockCommon, type EtchBlockContext, type EtchBlockJson, type EtchBlockOptions, type EtchBlockScript, type EtchBlockType, type EtchBlockTypeName, type EtchBlocksApi, type EtchBridgeConnection, type EtchComponentBlockJson, type EtchComponentsApi, type EtchConditionBlockJson, type EtchDynamicElementBlockJson, type EtchDynamicImageBlockJson, type EtchElementBlockJson, type EtchFieldsApi, type EtchHistoryApi, type EtchHtmlAttributes, type EtchLoop, type EtchLoopBlockJson, type EtchLoopConfig, type EtchLoopObj, type EtchLoopsApi, type EtchNavigationApi, type EtchPassthroughBlockJson, type EtchPostContentBlockJson, type EtchRawHtmlBlockJson, type EtchSlotContentBlockJson, type EtchSlotPlaceholderBlockJson, type EtchStylesApi, type EtchStylesheetsApi, type EtchSvgBlockJson, type EtchTextBlockJson, type EtchUiApi, type FindBlocksPredicate, type GroupComponentProperty, type GutenbergBlock, type LoopParamRef, type MetaQueryItem, type NavigationPlace, type NumberComponentProperty, type NumericParam, type ObjectComponentProperty, type PostCustomFieldGroupEntry, type PostCustomFieldValueEntry, type PostCustomFieldValueResponse, type PostCustomFieldValuesResponse, type PostSummary, type PublicBlockJson, type PublicComponentJson, type PublicComponentSummary, type RepeaterComponentProperty, type ResolvedCustomField, type SelectOptionsString, type StringComponentProperty, type StyleListFilter, type StylePatch, type StyleSelectorType, type StyleSummary, type StylesheetInput, type StylesheetPatch, type StylesheetSummary, type StylesheetType, type TaxQueryItem, type TemplateSummary, type WpQueryArgs, type WpTermsArgs, type WpUsersArgs, getEtch, isEtchApiError, isEtchAvailable };
+export { type ArrayComponentProperty, type BlockLoopBinding, type BlockPatch, type BooleanComponentProperty, type BooleanParam, type BridgeConnectOptions, type ClassComponentProperty, type ColorScheme, type ComponentPatch, type ComponentProperty, type ComponentPropertyBase, type ConditionComponentProperty, type ConnectOptions, type CopyObject, type CustomField, type CustomFieldAssignment, type CustomFieldGroup, type CustomFieldType, ETCH_API_VERSION, type Etch, EtchApiError, type EtchApiErrorCode, type EtchBlockCommon, type EtchBlockContext, type EtchBlockJson, type EtchBlockOptions, type EtchBlockScript, type EtchBlockType, type EtchBlockTypeName, type EtchBlocksApi, type EtchBridgeConnection, type EtchComponentBlockJson, type EtchComponentsApi, type EtchConditionBlockJson, type EtchDynamicElementBlockJson, type EtchDynamicImageBlockJson, type EtchElementBlockJson, type EtchFieldsApi, type EtchHistoryApi, type EtchHtmlAttributes, type EtchLoop, type EtchLoopBlockJson, type EtchLoopConfig, type EtchLoopObj, type EtchLoopsApi, type EtchNavigationApi, type EtchPassthroughBlockJson, type EtchPostContentBlockJson, type EtchRawHtmlBlockJson, type EtchSlotContentBlockJson, type EtchSlotPlaceholderBlockJson, type EtchStylesApi, type EtchStylesheetsApi, type EtchSvgBlockJson, type EtchTextBlockJson, type EtchUiApi, type FindBlocksPredicate, type GroupComponentProperty, type GutenbergBlock, type LoopParamRef, type MetaQueryItem, type NavigationPlace, type NumberComponentProperty, type NumericParam, type ObjectComponentProperty, type PostCustomFieldGroupEntry, type PostCustomFieldValueEntry, type PostCustomFieldValueResponse, type PostCustomFieldValuesResponse, type PostSummary, type PublicBlockJson, type PublicComponentJson, type PublicComponentSummary, type RepeaterComponentProperty, type ResolvedCustomField, type SelectOptionsString, type StringComponentProperty, type StyleListFilter, type StylePatch, type StyleSelectorType, type StyleSummary, type StylesheetInput, type StylesheetPatch, type StylesheetSummary, type StylesheetType, type TaxQueryItem, type TemplateSummary, type WpQueryArgs, type WpTermsArgs, type WpUsersArgs, getEtch, isEtchApiError, isEtchAvailable };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@digital-gravy/etch-public-api",
-	"version": "0.7.1",
+	"version": "0.7.2",
 	"description": "MIT-licensed typed client and contract for the Etch builder scripting API (window.etch). Etch itself is a separate proprietary product governed by its own commercial terms.",
 	"license": "MIT",
 	"repository": {