@digital-gravy/etch-public-api 0.1.0 → 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 +172 -36
- package/dist/index.d.ts +172 -36
- 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`). */
|
|
@@ -163,6 +280,25 @@ interface EtchBlocksApi {
|
|
|
163
280
|
/** Whether the block currently has the given CSS class. */
|
|
164
281
|
hasClass(blockId: string, className: string): boolean;
|
|
165
282
|
}
|
|
283
|
+
/**
|
|
284
|
+
* A loop parameter reference, e.g. `$count`. Resolved to a concrete value
|
|
285
|
+
* before the query runs.
|
|
286
|
+
*/
|
|
287
|
+
type LoopParamRef = `$${string}`;
|
|
288
|
+
/**
|
|
289
|
+
* A numeric query value, or a loop-parameter expression that resolves to one:
|
|
290
|
+
* a bare reference (`$count`) or a reference with a numeric fallback
|
|
291
|
+
* (`$count ?? 10`). Plain numeric strings (e.g. `"10"`) are not accepted —
|
|
292
|
+
* pass the number itself.
|
|
293
|
+
*/
|
|
294
|
+
type NumericParam = number | LoopParamRef | `$${string} ?? ${number}`;
|
|
295
|
+
/**
|
|
296
|
+
* A boolean query value, or a loop-parameter expression that resolves to one:
|
|
297
|
+
* a bare reference (`$sticky`) or a reference with a boolean fallback
|
|
298
|
+
* (`$sticky ?? false`). WordPress also accepts its integer-boolean convention
|
|
299
|
+
* (`0`/`1`) for these args.
|
|
300
|
+
*/
|
|
301
|
+
type BooleanParam = boolean | 0 | 1 | LoopParamRef | `$${string} ?? ${boolean}`;
|
|
166
302
|
/**
|
|
167
303
|
* A `WP_Query` meta-query clause. Extensible — additional keys are allowed.
|
|
168
304
|
* @see https://developer.wordpress.org/reference/classes/wp_query/#custom-field-post-meta-parameters
|
|
@@ -204,13 +340,13 @@ interface WpQueryArgs {
|
|
|
204
340
|
/** Post type(s) to query. */
|
|
205
341
|
post_type?: string | string[];
|
|
206
342
|
/** Number of posts per page (`-1` for all). */
|
|
207
|
-
posts_per_page?:
|
|
343
|
+
posts_per_page?: NumericParam;
|
|
208
344
|
/** Number of posts to skip. */
|
|
209
|
-
offset?:
|
|
345
|
+
offset?: NumericParam;
|
|
210
346
|
/** Page of results to return. */
|
|
211
|
-
paged?:
|
|
347
|
+
paged?: NumericParam;
|
|
212
348
|
/** Alias of `paged` used in some contexts. */
|
|
213
|
-
page?:
|
|
349
|
+
page?: NumericParam;
|
|
214
350
|
/** Field to order results by. */
|
|
215
351
|
orderby?: "date" | "title" | "menu_order" | "rand" | "ID" | "author" | "name" | "modified" | "parent" | "comment_count" | (string & {});
|
|
216
352
|
/** Sort direction. */
|
|
@@ -218,7 +354,7 @@ interface WpQueryArgs {
|
|
|
218
354
|
/** Post status to include. */
|
|
219
355
|
post_status?: "publish" | "pending" | "draft" | "auto-draft" | "future" | "private" | "inherit" | "trash" | (string & {});
|
|
220
356
|
/** Whether to ignore sticky posts. */
|
|
221
|
-
ignore_sticky_posts?:
|
|
357
|
+
ignore_sticky_posts?: BooleanParam;
|
|
222
358
|
/** Author id (number) or username (string). */
|
|
223
359
|
author?: number | string;
|
|
224
360
|
/** Author by `user_nicename`. */
|
|
@@ -264,11 +400,11 @@ interface WpUsersArgs {
|
|
|
264
400
|
/** Sort direction. */
|
|
265
401
|
order?: "ASC" | "DESC" | (string & {});
|
|
266
402
|
/** Number of users to return. */
|
|
267
|
-
number?:
|
|
403
|
+
number?: NumericParam;
|
|
268
404
|
/** Number of users to skip. */
|
|
269
|
-
offset?:
|
|
405
|
+
offset?: NumericParam;
|
|
270
406
|
/** Page of results to return. */
|
|
271
|
-
paged?:
|
|
407
|
+
paged?: NumericParam;
|
|
272
408
|
[key: string]: unknown;
|
|
273
409
|
}
|
|
274
410
|
/** Type-specific configuration of an {@link EtchLoop}, discriminated by `type`. */
|
|
@@ -881,4 +1017,4 @@ declare function isEtchApiError(value: unknown): value is EtchApiError;
|
|
|
881
1017
|
*/
|
|
882
1018
|
declare const ETCH_API_VERSION = "0.x";
|
|
883
1019
|
|
|
884
|
-
export { type ArrayComponentProperty, type BlockLoopBinding, type BlockPatch, type BooleanComponentProperty, 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 MetaQueryItem, type NavigationPlace, type NumberComponentProperty, 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`). */
|
|
@@ -163,6 +280,25 @@ interface EtchBlocksApi {
|
|
|
163
280
|
/** Whether the block currently has the given CSS class. */
|
|
164
281
|
hasClass(blockId: string, className: string): boolean;
|
|
165
282
|
}
|
|
283
|
+
/**
|
|
284
|
+
* A loop parameter reference, e.g. `$count`. Resolved to a concrete value
|
|
285
|
+
* before the query runs.
|
|
286
|
+
*/
|
|
287
|
+
type LoopParamRef = `$${string}`;
|
|
288
|
+
/**
|
|
289
|
+
* A numeric query value, or a loop-parameter expression that resolves to one:
|
|
290
|
+
* a bare reference (`$count`) or a reference with a numeric fallback
|
|
291
|
+
* (`$count ?? 10`). Plain numeric strings (e.g. `"10"`) are not accepted —
|
|
292
|
+
* pass the number itself.
|
|
293
|
+
*/
|
|
294
|
+
type NumericParam = number | LoopParamRef | `$${string} ?? ${number}`;
|
|
295
|
+
/**
|
|
296
|
+
* A boolean query value, or a loop-parameter expression that resolves to one:
|
|
297
|
+
* a bare reference (`$sticky`) or a reference with a boolean fallback
|
|
298
|
+
* (`$sticky ?? false`). WordPress also accepts its integer-boolean convention
|
|
299
|
+
* (`0`/`1`) for these args.
|
|
300
|
+
*/
|
|
301
|
+
type BooleanParam = boolean | 0 | 1 | LoopParamRef | `$${string} ?? ${boolean}`;
|
|
166
302
|
/**
|
|
167
303
|
* A `WP_Query` meta-query clause. Extensible — additional keys are allowed.
|
|
168
304
|
* @see https://developer.wordpress.org/reference/classes/wp_query/#custom-field-post-meta-parameters
|
|
@@ -204,13 +340,13 @@ interface WpQueryArgs {
|
|
|
204
340
|
/** Post type(s) to query. */
|
|
205
341
|
post_type?: string | string[];
|
|
206
342
|
/** Number of posts per page (`-1` for all). */
|
|
207
|
-
posts_per_page?:
|
|
343
|
+
posts_per_page?: NumericParam;
|
|
208
344
|
/** Number of posts to skip. */
|
|
209
|
-
offset?:
|
|
345
|
+
offset?: NumericParam;
|
|
210
346
|
/** Page of results to return. */
|
|
211
|
-
paged?:
|
|
347
|
+
paged?: NumericParam;
|
|
212
348
|
/** Alias of `paged` used in some contexts. */
|
|
213
|
-
page?:
|
|
349
|
+
page?: NumericParam;
|
|
214
350
|
/** Field to order results by. */
|
|
215
351
|
orderby?: "date" | "title" | "menu_order" | "rand" | "ID" | "author" | "name" | "modified" | "parent" | "comment_count" | (string & {});
|
|
216
352
|
/** Sort direction. */
|
|
@@ -218,7 +354,7 @@ interface WpQueryArgs {
|
|
|
218
354
|
/** Post status to include. */
|
|
219
355
|
post_status?: "publish" | "pending" | "draft" | "auto-draft" | "future" | "private" | "inherit" | "trash" | (string & {});
|
|
220
356
|
/** Whether to ignore sticky posts. */
|
|
221
|
-
ignore_sticky_posts?:
|
|
357
|
+
ignore_sticky_posts?: BooleanParam;
|
|
222
358
|
/** Author id (number) or username (string). */
|
|
223
359
|
author?: number | string;
|
|
224
360
|
/** Author by `user_nicename`. */
|
|
@@ -264,11 +400,11 @@ interface WpUsersArgs {
|
|
|
264
400
|
/** Sort direction. */
|
|
265
401
|
order?: "ASC" | "DESC" | (string & {});
|
|
266
402
|
/** Number of users to return. */
|
|
267
|
-
number?:
|
|
403
|
+
number?: NumericParam;
|
|
268
404
|
/** Number of users to skip. */
|
|
269
|
-
offset?:
|
|
405
|
+
offset?: NumericParam;
|
|
270
406
|
/** Page of results to return. */
|
|
271
|
-
paged?:
|
|
407
|
+
paged?: NumericParam;
|
|
272
408
|
[key: string]: unknown;
|
|
273
409
|
}
|
|
274
410
|
/** Type-specific configuration of an {@link EtchLoop}, discriminated by `type`. */
|
|
@@ -881,4 +1017,4 @@ declare function isEtchApiError(value: unknown): value is EtchApiError;
|
|
|
881
1017
|
*/
|
|
882
1018
|
declare const ETCH_API_VERSION = "0.x";
|
|
883
1019
|
|
|
884
|
-
export { type ArrayComponentProperty, type BlockLoopBinding, type BlockPatch, type BooleanComponentProperty, 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 MetaQueryItem, type NavigationPlace, type NumberComponentProperty, 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",
|