@digital-gravy/etch-public-api 0.1.1 → 0.2.0
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/dist/index.d.cts +145 -28
- package/dist/index.d.ts +145 -28
- package/package.json +1 -1
package/dist/index.d.cts
CHANGED
|
@@ -42,14 +42,28 @@ interface EtchBlockScript {
|
|
|
42
42
|
interface EtchBlockOptions {
|
|
43
43
|
[key: string]: unknown;
|
|
44
44
|
}
|
|
45
|
+
/** HTML attributes of a block. A value of `undefined` clears that attribute. */
|
|
46
|
+
type EtchHtmlAttributes = Record<string, string | undefined>;
|
|
45
47
|
/**
|
|
46
|
-
* A
|
|
47
|
-
* `
|
|
48
|
-
* fields, so the shape is intentionally extensible.
|
|
48
|
+
* A parsed Gutenberg block (WordPress block grammar), as carried by an
|
|
49
|
+
* `etch/passthrough` block. `attrs` is an open bag.
|
|
49
50
|
*/
|
|
50
|
-
interface
|
|
51
|
-
/**
|
|
52
|
-
|
|
51
|
+
interface GutenbergBlock {
|
|
52
|
+
/** Block name, e.g. `core/paragraph`. */
|
|
53
|
+
blockName: string;
|
|
54
|
+
/** Nested Gutenberg blocks. */
|
|
55
|
+
innerBlocks: GutenbergBlock[];
|
|
56
|
+
/** Rendered inner HTML. */
|
|
57
|
+
innerHTML: string;
|
|
58
|
+
/** Inner-content fragments (`null` marks an inner-block insertion point). */
|
|
59
|
+
innerContent: (string | null)[];
|
|
60
|
+
/** Block attributes. */
|
|
61
|
+
attrs: {
|
|
62
|
+
[key: string]: unknown;
|
|
63
|
+
};
|
|
64
|
+
}
|
|
65
|
+
/** Fields shared by every block, whatever its `type`. */
|
|
66
|
+
interface EtchBlockCommon {
|
|
53
67
|
/** Schema version of this block type. */
|
|
54
68
|
version: number;
|
|
55
69
|
/** Editor-facing metadata (label, hidden, structure state). */
|
|
@@ -58,36 +72,139 @@ interface EtchBlockJson {
|
|
|
58
72
|
script?: EtchBlockScript;
|
|
59
73
|
/** Optional block-type-specific options. */
|
|
60
74
|
options?: EtchBlockOptions;
|
|
61
|
-
/** Child blocks, each itself an
|
|
75
|
+
/** Child blocks, each itself an {@link EtchBlockJson}. */
|
|
62
76
|
children: EtchBlockJson[];
|
|
63
|
-
|
|
64
|
-
|
|
77
|
+
}
|
|
78
|
+
/** A text block (`etch/text`). */
|
|
79
|
+
interface EtchTextBlockJson extends EtchBlockCommon {
|
|
80
|
+
type: "etch/text";
|
|
81
|
+
/** The block's text content. */
|
|
82
|
+
text: string;
|
|
83
|
+
}
|
|
84
|
+
/** A static HTML element block (`etch/element`) with a concrete tag. */
|
|
85
|
+
interface EtchElementBlockJson extends EtchBlockCommon {
|
|
86
|
+
type: "etch/element";
|
|
87
|
+
/** The HTML tag name, e.g. `div`, `p`, `h1`. */
|
|
88
|
+
tag: string;
|
|
89
|
+
/** HTML attributes. */
|
|
90
|
+
attributes: EtchHtmlAttributes;
|
|
91
|
+
/** Ids of the global styles applied to this block. */
|
|
92
|
+
styles: string[];
|
|
65
93
|
}
|
|
66
94
|
/**
|
|
67
|
-
* A
|
|
68
|
-
*
|
|
69
|
-
* recursively, so every node in `children` is itself a `PublicBlockJson`.
|
|
95
|
+
* A dynamic element block (`etch/dynamic-element`). Its rendered tag is read
|
|
96
|
+
* from `attributes.tag` rather than a dedicated field.
|
|
70
97
|
*/
|
|
71
|
-
interface
|
|
98
|
+
interface EtchDynamicElementBlockJson extends EtchBlockCommon {
|
|
99
|
+
type: "etch/dynamic-element";
|
|
100
|
+
/** HTML attributes (the rendered tag is read from `attributes.tag`). */
|
|
101
|
+
attributes: EtchHtmlAttributes;
|
|
102
|
+
/** Ids of the global styles applied to this block. */
|
|
103
|
+
styles: string[];
|
|
104
|
+
}
|
|
105
|
+
/** A dynamic image block (`etch/dynamic-image`), rendered as an `<img>`. */
|
|
106
|
+
interface EtchDynamicImageBlockJson extends EtchBlockCommon {
|
|
107
|
+
type: "etch/dynamic-image";
|
|
108
|
+
/** HTML attributes (e.g. `src`, `alt`). */
|
|
109
|
+
attributes: EtchHtmlAttributes;
|
|
110
|
+
/** Ids of the global styles applied to this block. */
|
|
111
|
+
styles: string[];
|
|
112
|
+
}
|
|
113
|
+
/** An inline SVG block (`etch/svg`). */
|
|
114
|
+
interface EtchSvgBlockJson extends EtchBlockCommon {
|
|
115
|
+
type: "etch/svg";
|
|
116
|
+
/** HTML/SVG attributes. */
|
|
117
|
+
attributes: EtchHtmlAttributes;
|
|
118
|
+
/** Ids of the global styles applied to this block. */
|
|
119
|
+
styles: string[];
|
|
120
|
+
}
|
|
121
|
+
/** A loop block (`etch/loop`) that repeats its children over a data source. */
|
|
122
|
+
interface EtchLoopBlockJson extends EtchBlockCommon {
|
|
123
|
+
type: "etch/loop";
|
|
124
|
+
/** Variable name bound to the current item (e.g. `item`). */
|
|
125
|
+
itemId: string;
|
|
126
|
+
/** What the block iterates over (a dynamic path); omitted when bound via `loopId`. */
|
|
127
|
+
target?: string;
|
|
128
|
+
/** Variable name bound to the current index. */
|
|
129
|
+
indexId?: string;
|
|
130
|
+
/** Id of a registered loop definition this block is bound to. */
|
|
131
|
+
loopId?: string;
|
|
132
|
+
/** Values for the bound loop's parameters. */
|
|
133
|
+
loopParams?: Record<string, unknown>;
|
|
134
|
+
}
|
|
135
|
+
/** A conditional block (`etch/condition`); renders its children when the expression holds. */
|
|
136
|
+
interface EtchConditionBlockJson extends EtchBlockCommon {
|
|
137
|
+
type: "etch/condition";
|
|
138
|
+
/** The condition expression. */
|
|
139
|
+
conditionString: string;
|
|
140
|
+
}
|
|
141
|
+
/** An instance of a reusable component (`etch/component`). */
|
|
142
|
+
interface EtchComponentBlockJson extends EtchBlockCommon {
|
|
143
|
+
type: "etch/component";
|
|
144
|
+
/** Id of the component being instantiated. */
|
|
145
|
+
componentId: number;
|
|
146
|
+
/** Values bound to the component's properties. */
|
|
147
|
+
attributes: EtchHtmlAttributes;
|
|
148
|
+
}
|
|
149
|
+
/** Content projected into a component slot (`etch/slot-content`). */
|
|
150
|
+
interface EtchSlotContentBlockJson extends EtchBlockCommon {
|
|
151
|
+
type: "etch/slot-content";
|
|
152
|
+
/** Name of the slot this content targets. */
|
|
153
|
+
slotName: string;
|
|
154
|
+
}
|
|
155
|
+
/** A slot placeholder inside a component definition (`etch/slot-placeholder`). */
|
|
156
|
+
interface EtchSlotPlaceholderBlockJson extends EtchBlockCommon {
|
|
157
|
+
type: "etch/slot-placeholder";
|
|
158
|
+
/** Name of the slot. */
|
|
159
|
+
slotName: string;
|
|
160
|
+
}
|
|
161
|
+
/** The post-content insertion point (`etch/post-content`). No extra fields. */
|
|
162
|
+
interface EtchPostContentBlockJson extends EtchBlockCommon {
|
|
163
|
+
type: "etch/post-content";
|
|
164
|
+
}
|
|
165
|
+
/** A raw-HTML block (`etch/raw-html`). */
|
|
166
|
+
interface EtchRawHtmlBlockJson extends EtchBlockCommon {
|
|
167
|
+
type: "etch/raw-html";
|
|
168
|
+
/** Sanitized HTML content. */
|
|
169
|
+
content: string;
|
|
170
|
+
/** The original, unsanitized HTML as authored. */
|
|
171
|
+
unsafe: string;
|
|
172
|
+
}
|
|
173
|
+
/** A pass-through wrapper around a native Gutenberg block (`etch/passthrough`). */
|
|
174
|
+
interface EtchPassthroughBlockJson extends EtchBlockCommon {
|
|
175
|
+
type: "etch/passthrough";
|
|
176
|
+
/** The wrapped Gutenberg block. */
|
|
177
|
+
gutenbergBlock: GutenbergBlock;
|
|
178
|
+
}
|
|
179
|
+
/**
|
|
180
|
+
* A block as plain, structured-clone-safe JSON — the shape accepted by
|
|
181
|
+
* `blocks.create()` / `blocks.replace()`.
|
|
182
|
+
*
|
|
183
|
+
* This is a **discriminated union** on `type`: the compiler flags a block whose
|
|
184
|
+
* payload does not match its declared `type` (e.g. an `etch/text` block missing
|
|
185
|
+
* `text`, or carrying an `etch/element`'s `tag`).
|
|
186
|
+
*/
|
|
187
|
+
type EtchBlockJson = EtchTextBlockJson | EtchElementBlockJson | EtchDynamicElementBlockJson | EtchDynamicImageBlockJson | EtchSvgBlockJson | EtchLoopBlockJson | EtchConditionBlockJson | EtchComponentBlockJson | EtchSlotContentBlockJson | EtchSlotPlaceholderBlockJson | EtchPostContentBlockJson | EtchRawHtmlBlockJson | EtchPassthroughBlockJson;
|
|
188
|
+
/** Every known block `type` string (the discriminants of {@link EtchBlockJson}). */
|
|
189
|
+
type EtchBlockTypeName = EtchBlockJson["type"];
|
|
190
|
+
/** Read-only identity attached to every serialized (read) block. */
|
|
191
|
+
interface BlockIdentity {
|
|
72
192
|
/** Stable id of this block. */
|
|
73
193
|
id: string;
|
|
74
|
-
/** Id of the parent block, or `null`
|
|
194
|
+
/** Id of the parent block, or `null` at the document root. */
|
|
75
195
|
parentId: string | null;
|
|
76
|
-
/**
|
|
77
|
-
type: EtchBlockType;
|
|
78
|
-
/** Schema version of this block type. */
|
|
79
|
-
version: number;
|
|
80
|
-
/** Editor-facing metadata (label, hidden, structure state). */
|
|
81
|
-
context: EtchBlockContext;
|
|
82
|
-
/** Optional inline script attached to the block. */
|
|
83
|
-
script?: EtchBlockScript;
|
|
84
|
-
/** Optional block-type-specific options. */
|
|
85
|
-
options?: EtchBlockOptions;
|
|
86
|
-
/** Child blocks, each itself a `PublicBlockJson` with its own id/parentId. */
|
|
196
|
+
/** Child blocks, each itself a `PublicBlockJson`. */
|
|
87
197
|
children: PublicBlockJson[];
|
|
88
|
-
/** Block-type-specific fields beyond the common ones above. */
|
|
89
|
-
[key: string]: unknown;
|
|
90
198
|
}
|
|
199
|
+
/** Attach read-only identity (`id`/`parentId`) to a block, recursively. */
|
|
200
|
+
type WithIdentity<B> = B extends EtchBlockCommon ? Omit<B, "children"> & BlockIdentity : never;
|
|
201
|
+
/**
|
|
202
|
+
* A block serialized for reading: an {@link EtchBlockJson} variant plus its
|
|
203
|
+
* `id` and `parentId` (`null` at the document root), attached recursively so
|
|
204
|
+
* every node in `children` is itself a `PublicBlockJson`. Still discriminated
|
|
205
|
+
* on `type`, so `switch (block.type)` narrows to the matching payload.
|
|
206
|
+
*/
|
|
207
|
+
type PublicBlockJson = WithIdentity<EtchBlockJson>;
|
|
91
208
|
/** Predicate accepted by `blocks.find()`. All provided fields must match (AND). */
|
|
92
209
|
interface FindBlocksPredicate {
|
|
93
210
|
/** Match blocks of this exact type (e.g. `etch/text`). */
|
|
@@ -900,4 +1017,4 @@ declare function isEtchApiError(value: unknown): value is EtchApiError;
|
|
|
900
1017
|
*/
|
|
901
1018
|
declare const ETCH_API_VERSION = "0.x";
|
|
902
1019
|
|
|
903
|
-
export { type ArrayComponentProperty, type BlockLoopBinding, type BlockPatch, type BooleanComponentProperty, type BooleanParam, 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 EtchBlockContext, type EtchBlockJson, type EtchBlockOptions, type EtchBlockScript, type EtchBlockType, type EtchBlocksApi, type EtchComponentsApi, type EtchFieldsApi, type EtchHistoryApi, type EtchLoop, type EtchLoopConfig, type EtchLoopObj, type EtchLoopsApi, type EtchNavigationApi, type EtchStylesApi, type EtchStylesheetsApi, type EtchUiApi, type FindBlocksPredicate, type GroupComponentProperty, 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 StringComponentProperty, type StylePatch, type StylesheetInput, type StylesheetPatch, type StylesheetSummary, type StylesheetType, type TaxQueryItem, type TemplateSummary, type WpQueryArgs, type WpTermsArgs, type WpUsersArgs, getEtch, isEtchApiError, isEtchAvailable };
|
|
1020
|
+
export { type ArrayComponentProperty, type BlockLoopBinding, type BlockPatch, type BooleanComponentProperty, type BooleanParam, 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 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 StringComponentProperty, type StylePatch, 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
CHANGED
|
@@ -42,14 +42,28 @@ interface EtchBlockScript {
|
|
|
42
42
|
interface EtchBlockOptions {
|
|
43
43
|
[key: string]: unknown;
|
|
44
44
|
}
|
|
45
|
+
/** HTML attributes of a block. A value of `undefined` clears that attribute. */
|
|
46
|
+
type EtchHtmlAttributes = Record<string, string | undefined>;
|
|
45
47
|
/**
|
|
46
|
-
* A
|
|
47
|
-
* `
|
|
48
|
-
* fields, so the shape is intentionally extensible.
|
|
48
|
+
* A parsed Gutenberg block (WordPress block grammar), as carried by an
|
|
49
|
+
* `etch/passthrough` block. `attrs` is an open bag.
|
|
49
50
|
*/
|
|
50
|
-
interface
|
|
51
|
-
/**
|
|
52
|
-
|
|
51
|
+
interface GutenbergBlock {
|
|
52
|
+
/** Block name, e.g. `core/paragraph`. */
|
|
53
|
+
blockName: string;
|
|
54
|
+
/** Nested Gutenberg blocks. */
|
|
55
|
+
innerBlocks: GutenbergBlock[];
|
|
56
|
+
/** Rendered inner HTML. */
|
|
57
|
+
innerHTML: string;
|
|
58
|
+
/** Inner-content fragments (`null` marks an inner-block insertion point). */
|
|
59
|
+
innerContent: (string | null)[];
|
|
60
|
+
/** Block attributes. */
|
|
61
|
+
attrs: {
|
|
62
|
+
[key: string]: unknown;
|
|
63
|
+
};
|
|
64
|
+
}
|
|
65
|
+
/** Fields shared by every block, whatever its `type`. */
|
|
66
|
+
interface EtchBlockCommon {
|
|
53
67
|
/** Schema version of this block type. */
|
|
54
68
|
version: number;
|
|
55
69
|
/** Editor-facing metadata (label, hidden, structure state). */
|
|
@@ -58,36 +72,139 @@ interface EtchBlockJson {
|
|
|
58
72
|
script?: EtchBlockScript;
|
|
59
73
|
/** Optional block-type-specific options. */
|
|
60
74
|
options?: EtchBlockOptions;
|
|
61
|
-
/** Child blocks, each itself an
|
|
75
|
+
/** Child blocks, each itself an {@link EtchBlockJson}. */
|
|
62
76
|
children: EtchBlockJson[];
|
|
63
|
-
|
|
64
|
-
|
|
77
|
+
}
|
|
78
|
+
/** A text block (`etch/text`). */
|
|
79
|
+
interface EtchTextBlockJson extends EtchBlockCommon {
|
|
80
|
+
type: "etch/text";
|
|
81
|
+
/** The block's text content. */
|
|
82
|
+
text: string;
|
|
83
|
+
}
|
|
84
|
+
/** A static HTML element block (`etch/element`) with a concrete tag. */
|
|
85
|
+
interface EtchElementBlockJson extends EtchBlockCommon {
|
|
86
|
+
type: "etch/element";
|
|
87
|
+
/** The HTML tag name, e.g. `div`, `p`, `h1`. */
|
|
88
|
+
tag: string;
|
|
89
|
+
/** HTML attributes. */
|
|
90
|
+
attributes: EtchHtmlAttributes;
|
|
91
|
+
/** Ids of the global styles applied to this block. */
|
|
92
|
+
styles: string[];
|
|
65
93
|
}
|
|
66
94
|
/**
|
|
67
|
-
* A
|
|
68
|
-
*
|
|
69
|
-
* recursively, so every node in `children` is itself a `PublicBlockJson`.
|
|
95
|
+
* A dynamic element block (`etch/dynamic-element`). Its rendered tag is read
|
|
96
|
+
* from `attributes.tag` rather than a dedicated field.
|
|
70
97
|
*/
|
|
71
|
-
interface
|
|
98
|
+
interface EtchDynamicElementBlockJson extends EtchBlockCommon {
|
|
99
|
+
type: "etch/dynamic-element";
|
|
100
|
+
/** HTML attributes (the rendered tag is read from `attributes.tag`). */
|
|
101
|
+
attributes: EtchHtmlAttributes;
|
|
102
|
+
/** Ids of the global styles applied to this block. */
|
|
103
|
+
styles: string[];
|
|
104
|
+
}
|
|
105
|
+
/** A dynamic image block (`etch/dynamic-image`), rendered as an `<img>`. */
|
|
106
|
+
interface EtchDynamicImageBlockJson extends EtchBlockCommon {
|
|
107
|
+
type: "etch/dynamic-image";
|
|
108
|
+
/** HTML attributes (e.g. `src`, `alt`). */
|
|
109
|
+
attributes: EtchHtmlAttributes;
|
|
110
|
+
/** Ids of the global styles applied to this block. */
|
|
111
|
+
styles: string[];
|
|
112
|
+
}
|
|
113
|
+
/** An inline SVG block (`etch/svg`). */
|
|
114
|
+
interface EtchSvgBlockJson extends EtchBlockCommon {
|
|
115
|
+
type: "etch/svg";
|
|
116
|
+
/** HTML/SVG attributes. */
|
|
117
|
+
attributes: EtchHtmlAttributes;
|
|
118
|
+
/** Ids of the global styles applied to this block. */
|
|
119
|
+
styles: string[];
|
|
120
|
+
}
|
|
121
|
+
/** A loop block (`etch/loop`) that repeats its children over a data source. */
|
|
122
|
+
interface EtchLoopBlockJson extends EtchBlockCommon {
|
|
123
|
+
type: "etch/loop";
|
|
124
|
+
/** Variable name bound to the current item (e.g. `item`). */
|
|
125
|
+
itemId: string;
|
|
126
|
+
/** What the block iterates over (a dynamic path); omitted when bound via `loopId`. */
|
|
127
|
+
target?: string;
|
|
128
|
+
/** Variable name bound to the current index. */
|
|
129
|
+
indexId?: string;
|
|
130
|
+
/** Id of a registered loop definition this block is bound to. */
|
|
131
|
+
loopId?: string;
|
|
132
|
+
/** Values for the bound loop's parameters. */
|
|
133
|
+
loopParams?: Record<string, unknown>;
|
|
134
|
+
}
|
|
135
|
+
/** A conditional block (`etch/condition`); renders its children when the expression holds. */
|
|
136
|
+
interface EtchConditionBlockJson extends EtchBlockCommon {
|
|
137
|
+
type: "etch/condition";
|
|
138
|
+
/** The condition expression. */
|
|
139
|
+
conditionString: string;
|
|
140
|
+
}
|
|
141
|
+
/** An instance of a reusable component (`etch/component`). */
|
|
142
|
+
interface EtchComponentBlockJson extends EtchBlockCommon {
|
|
143
|
+
type: "etch/component";
|
|
144
|
+
/** Id of the component being instantiated. */
|
|
145
|
+
componentId: number;
|
|
146
|
+
/** Values bound to the component's properties. */
|
|
147
|
+
attributes: EtchHtmlAttributes;
|
|
148
|
+
}
|
|
149
|
+
/** Content projected into a component slot (`etch/slot-content`). */
|
|
150
|
+
interface EtchSlotContentBlockJson extends EtchBlockCommon {
|
|
151
|
+
type: "etch/slot-content";
|
|
152
|
+
/** Name of the slot this content targets. */
|
|
153
|
+
slotName: string;
|
|
154
|
+
}
|
|
155
|
+
/** A slot placeholder inside a component definition (`etch/slot-placeholder`). */
|
|
156
|
+
interface EtchSlotPlaceholderBlockJson extends EtchBlockCommon {
|
|
157
|
+
type: "etch/slot-placeholder";
|
|
158
|
+
/** Name of the slot. */
|
|
159
|
+
slotName: string;
|
|
160
|
+
}
|
|
161
|
+
/** The post-content insertion point (`etch/post-content`). No extra fields. */
|
|
162
|
+
interface EtchPostContentBlockJson extends EtchBlockCommon {
|
|
163
|
+
type: "etch/post-content";
|
|
164
|
+
}
|
|
165
|
+
/** A raw-HTML block (`etch/raw-html`). */
|
|
166
|
+
interface EtchRawHtmlBlockJson extends EtchBlockCommon {
|
|
167
|
+
type: "etch/raw-html";
|
|
168
|
+
/** Sanitized HTML content. */
|
|
169
|
+
content: string;
|
|
170
|
+
/** The original, unsanitized HTML as authored. */
|
|
171
|
+
unsafe: string;
|
|
172
|
+
}
|
|
173
|
+
/** A pass-through wrapper around a native Gutenberg block (`etch/passthrough`). */
|
|
174
|
+
interface EtchPassthroughBlockJson extends EtchBlockCommon {
|
|
175
|
+
type: "etch/passthrough";
|
|
176
|
+
/** The wrapped Gutenberg block. */
|
|
177
|
+
gutenbergBlock: GutenbergBlock;
|
|
178
|
+
}
|
|
179
|
+
/**
|
|
180
|
+
* A block as plain, structured-clone-safe JSON — the shape accepted by
|
|
181
|
+
* `blocks.create()` / `blocks.replace()`.
|
|
182
|
+
*
|
|
183
|
+
* This is a **discriminated union** on `type`: the compiler flags a block whose
|
|
184
|
+
* payload does not match its declared `type` (e.g. an `etch/text` block missing
|
|
185
|
+
* `text`, or carrying an `etch/element`'s `tag`).
|
|
186
|
+
*/
|
|
187
|
+
type EtchBlockJson = EtchTextBlockJson | EtchElementBlockJson | EtchDynamicElementBlockJson | EtchDynamicImageBlockJson | EtchSvgBlockJson | EtchLoopBlockJson | EtchConditionBlockJson | EtchComponentBlockJson | EtchSlotContentBlockJson | EtchSlotPlaceholderBlockJson | EtchPostContentBlockJson | EtchRawHtmlBlockJson | EtchPassthroughBlockJson;
|
|
188
|
+
/** Every known block `type` string (the discriminants of {@link EtchBlockJson}). */
|
|
189
|
+
type EtchBlockTypeName = EtchBlockJson["type"];
|
|
190
|
+
/** Read-only identity attached to every serialized (read) block. */
|
|
191
|
+
interface BlockIdentity {
|
|
72
192
|
/** Stable id of this block. */
|
|
73
193
|
id: string;
|
|
74
|
-
/** Id of the parent block, or `null`
|
|
194
|
+
/** Id of the parent block, or `null` at the document root. */
|
|
75
195
|
parentId: string | null;
|
|
76
|
-
/**
|
|
77
|
-
type: EtchBlockType;
|
|
78
|
-
/** Schema version of this block type. */
|
|
79
|
-
version: number;
|
|
80
|
-
/** Editor-facing metadata (label, hidden, structure state). */
|
|
81
|
-
context: EtchBlockContext;
|
|
82
|
-
/** Optional inline script attached to the block. */
|
|
83
|
-
script?: EtchBlockScript;
|
|
84
|
-
/** Optional block-type-specific options. */
|
|
85
|
-
options?: EtchBlockOptions;
|
|
86
|
-
/** Child blocks, each itself a `PublicBlockJson` with its own id/parentId. */
|
|
196
|
+
/** Child blocks, each itself a `PublicBlockJson`. */
|
|
87
197
|
children: PublicBlockJson[];
|
|
88
|
-
/** Block-type-specific fields beyond the common ones above. */
|
|
89
|
-
[key: string]: unknown;
|
|
90
198
|
}
|
|
199
|
+
/** Attach read-only identity (`id`/`parentId`) to a block, recursively. */
|
|
200
|
+
type WithIdentity<B> = B extends EtchBlockCommon ? Omit<B, "children"> & BlockIdentity : never;
|
|
201
|
+
/**
|
|
202
|
+
* A block serialized for reading: an {@link EtchBlockJson} variant plus its
|
|
203
|
+
* `id` and `parentId` (`null` at the document root), attached recursively so
|
|
204
|
+
* every node in `children` is itself a `PublicBlockJson`. Still discriminated
|
|
205
|
+
* on `type`, so `switch (block.type)` narrows to the matching payload.
|
|
206
|
+
*/
|
|
207
|
+
type PublicBlockJson = WithIdentity<EtchBlockJson>;
|
|
91
208
|
/** Predicate accepted by `blocks.find()`. All provided fields must match (AND). */
|
|
92
209
|
interface FindBlocksPredicate {
|
|
93
210
|
/** Match blocks of this exact type (e.g. `etch/text`). */
|
|
@@ -900,4 +1017,4 @@ declare function isEtchApiError(value: unknown): value is EtchApiError;
|
|
|
900
1017
|
*/
|
|
901
1018
|
declare const ETCH_API_VERSION = "0.x";
|
|
902
1019
|
|
|
903
|
-
export { type ArrayComponentProperty, type BlockLoopBinding, type BlockPatch, type BooleanComponentProperty, type BooleanParam, 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 EtchBlockContext, type EtchBlockJson, type EtchBlockOptions, type EtchBlockScript, type EtchBlockType, type EtchBlocksApi, type EtchComponentsApi, type EtchFieldsApi, type EtchHistoryApi, type EtchLoop, type EtchLoopConfig, type EtchLoopObj, type EtchLoopsApi, type EtchNavigationApi, type EtchStylesApi, type EtchStylesheetsApi, type EtchUiApi, type FindBlocksPredicate, type GroupComponentProperty, 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 StringComponentProperty, type StylePatch, type StylesheetInput, type StylesheetPatch, type StylesheetSummary, type StylesheetType, type TaxQueryItem, type TemplateSummary, type WpQueryArgs, type WpTermsArgs, type WpUsersArgs, getEtch, isEtchApiError, isEtchAvailable };
|
|
1020
|
+
export { type ArrayComponentProperty, type BlockLoopBinding, type BlockPatch, type BooleanComponentProperty, type BooleanParam, 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 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 StringComponentProperty, type StylePatch, type StylesheetInput, type StylesheetPatch, type StylesheetSummary, type StylesheetType, type TaxQueryItem, type TemplateSummary, type WpQueryArgs, type WpTermsArgs, type WpUsersArgs, getEtch, isEtchApiError, isEtchAvailable };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@digital-gravy/etch-public-api",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"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.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|