@digital-gravy/etch-public-api 0.7.2 → 0.7.4
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 +218 -200
- package/dist/index.d.ts +218 -200
- package/package.json +1 -1
package/dist/index.d.cts
CHANGED
|
@@ -1,6 +1,208 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Loop definitions, WordPress query argument shapes, and the `etch.loops` API
|
|
3
|
+
* surface.
|
|
4
|
+
*/
|
|
5
|
+
/**
|
|
6
|
+
* A loop parameter reference, e.g. `$count`. Resolved to a concrete value
|
|
7
|
+
* before the query runs.
|
|
8
|
+
*/
|
|
9
|
+
type LoopParamRef = `$${string}`;
|
|
10
|
+
/**
|
|
11
|
+
* A numeric query value, or a loop-parameter expression that resolves to one:
|
|
12
|
+
* a bare reference (`$count`) or a reference with a numeric fallback
|
|
13
|
+
* (`$count ?? 10`). Plain numeric strings (e.g. `"10"`) are not accepted —
|
|
14
|
+
* pass the number itself.
|
|
15
|
+
*/
|
|
16
|
+
type NumericParam = number | LoopParamRef | `$${string} ?? ${number}`;
|
|
17
|
+
/**
|
|
18
|
+
* A boolean query value, or a loop-parameter expression that resolves to one:
|
|
19
|
+
* a bare reference (`$sticky`) or a reference with a boolean fallback
|
|
20
|
+
* (`$sticky ?? false`). WordPress also accepts its integer-boolean convention
|
|
21
|
+
* (`0`/`1`) for these args.
|
|
22
|
+
*/
|
|
23
|
+
type BooleanParam = boolean | 0 | 1 | LoopParamRef | `$${string} ?? ${boolean}`;
|
|
24
|
+
/**
|
|
25
|
+
* A `WP_Query` meta-query clause. Extensible — additional keys are allowed.
|
|
26
|
+
* @see https://developer.wordpress.org/reference/classes/wp_query/#custom-field-post-meta-parameters
|
|
27
|
+
*/
|
|
28
|
+
interface MetaQueryItem {
|
|
29
|
+
/** The custom field (meta) key to compare. */
|
|
30
|
+
key: string;
|
|
31
|
+
/** The value(s) to compare against. */
|
|
32
|
+
value: string | number | Array<string | number>;
|
|
33
|
+
/** Comparison operator (defaults to `=`). */
|
|
34
|
+
compare?: '=' | '!=' | '>' | '>=' | '<' | '<=' | 'LIKE' | 'NOT LIKE' | 'IN' | 'NOT IN' | 'BETWEEN' | 'NOT BETWEEN' | 'EXISTS' | 'NOT EXISTS';
|
|
35
|
+
/** SQL type the value is cast to before comparison. */
|
|
36
|
+
type?: 'NUMERIC' | 'BINARY' | 'CHAR' | 'DATE' | 'DATETIME' | 'DECIMAL' | 'SIGNED' | 'TIME' | 'UNSIGNED';
|
|
37
|
+
[key: string]: unknown;
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* A `WP_Query` taxonomy-query clause. Extensible — additional keys are allowed.
|
|
41
|
+
* @see https://developer.wordpress.org/reference/classes/wp_query/#taxonomy-parameters
|
|
42
|
+
*/
|
|
43
|
+
interface TaxQueryItem {
|
|
44
|
+
/** The taxonomy to query (e.g. `category`, `post_tag`). */
|
|
45
|
+
taxonomy: string;
|
|
46
|
+
/** Which term field `terms` refers to. */
|
|
47
|
+
field: 'term_id' | 'slug' | 'name';
|
|
48
|
+
/** The term(s) to match. */
|
|
49
|
+
terms: string | number | Array<string | number>;
|
|
50
|
+
/** How to match the terms (defaults to `IN`). */
|
|
51
|
+
operator?: 'IN' | 'NOT IN' | 'AND';
|
|
52
|
+
/** Whether to include child terms of a hierarchical taxonomy. */
|
|
53
|
+
include_children?: boolean;
|
|
54
|
+
[key: string]: unknown;
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* WordPress query arguments. Values may be static or a loop parameter
|
|
58
|
+
* expression (`"$param"` or `"$param ?? fallback"`). Extensible — any
|
|
59
|
+
* additional `WP_Query` argument is allowed.
|
|
60
|
+
*/
|
|
61
|
+
interface WpQueryArgs {
|
|
62
|
+
/** Post type(s) to query. */
|
|
63
|
+
post_type?: string | string[];
|
|
64
|
+
/** Number of posts per page (`-1` for all). */
|
|
65
|
+
posts_per_page?: NumericParam;
|
|
66
|
+
/** Number of posts to skip. */
|
|
67
|
+
offset?: NumericParam;
|
|
68
|
+
/** Page of results to return. */
|
|
69
|
+
paged?: NumericParam;
|
|
70
|
+
/** Alias of `paged` used in some contexts. */
|
|
71
|
+
page?: NumericParam;
|
|
72
|
+
/** Field to order results by. */
|
|
73
|
+
orderby?: 'date' | 'title' | 'menu_order' | 'rand' | 'ID' | 'author' | 'name' | 'modified' | 'parent' | 'comment_count' | (string & {});
|
|
74
|
+
/** Sort direction. */
|
|
75
|
+
order?: 'ASC' | 'DESC' | (string & {});
|
|
76
|
+
/** Post status to include. */
|
|
77
|
+
post_status?: 'publish' | 'pending' | 'draft' | 'auto-draft' | 'future' | 'private' | 'inherit' | 'trash' | (string & {});
|
|
78
|
+
/** Whether to ignore sticky posts. */
|
|
79
|
+
ignore_sticky_posts?: BooleanParam;
|
|
80
|
+
/** Author id (number) or username (string). */
|
|
81
|
+
author?: number | string;
|
|
82
|
+
/** Author by `user_nicename`. */
|
|
83
|
+
author_name?: string;
|
|
84
|
+
/** Category id (number) or slug (string). */
|
|
85
|
+
category?: number | string;
|
|
86
|
+
/** Category by slug. */
|
|
87
|
+
category_name?: string;
|
|
88
|
+
/** Tag slug. */
|
|
89
|
+
tag?: string;
|
|
90
|
+
/** Taxonomy query clauses. */
|
|
91
|
+
tax_query?: TaxQueryItem[];
|
|
92
|
+
/** Meta (custom field) query clauses. */
|
|
93
|
+
meta_query?: MetaQueryItem[];
|
|
94
|
+
/** Search keyword. */
|
|
95
|
+
s?: string;
|
|
96
|
+
[key: string]: unknown;
|
|
97
|
+
}
|
|
98
|
+
/** WordPress taxonomy-term query arguments (extensible). */
|
|
99
|
+
interface WpTermsArgs {
|
|
100
|
+
/** Taxonomy to fetch terms from. */
|
|
101
|
+
taxonomy?: string;
|
|
102
|
+
/** Field to order terms by. */
|
|
103
|
+
orderby?: 'name' | 'slug' | 'term_group' | 'term_id' | 'description' | 'count' | (string & {});
|
|
104
|
+
/** Sort direction. */
|
|
105
|
+
order?: 'ASC' | 'DESC' | (string & {});
|
|
106
|
+
[key: string]: unknown;
|
|
107
|
+
}
|
|
108
|
+
/** WordPress user query arguments (extensible). */
|
|
109
|
+
interface WpUsersArgs {
|
|
110
|
+
/** Role(s) users must have. */
|
|
111
|
+
role?: string | string[];
|
|
112
|
+
/** User ids to include. */
|
|
113
|
+
include?: number[] | string;
|
|
114
|
+
/** User ids to exclude. */
|
|
115
|
+
exclude?: number[] | string;
|
|
116
|
+
/** Search keyword. */
|
|
117
|
+
search?: string;
|
|
118
|
+
/** Columns the `search` keyword is matched against. */
|
|
119
|
+
search_columns?: string[] | string;
|
|
120
|
+
/** Field to order users by. */
|
|
121
|
+
orderby?: 'ID' | 'display_name' | 'name' | 'user_login' | 'user_email' | 'user_registered' | 'post_count' | 'meta_value' | 'meta_value_num' | (string & {});
|
|
122
|
+
/** Sort direction. */
|
|
123
|
+
order?: 'ASC' | 'DESC' | (string & {});
|
|
124
|
+
/** Number of users to return. */
|
|
125
|
+
number?: NumericParam;
|
|
126
|
+
/** Number of users to skip. */
|
|
127
|
+
offset?: NumericParam;
|
|
128
|
+
/** Page of results to return. */
|
|
129
|
+
paged?: NumericParam;
|
|
130
|
+
[key: string]: unknown;
|
|
131
|
+
}
|
|
132
|
+
/** Type-specific configuration of an {@link EtchLoop}, discriminated by `type`. */
|
|
133
|
+
type EtchLoopConfig = {
|
|
134
|
+
type: 'wp-query';
|
|
135
|
+
args: WpQueryArgs;
|
|
136
|
+
} | {
|
|
137
|
+
type: 'wp-terms';
|
|
138
|
+
args: WpTermsArgs;
|
|
139
|
+
} | {
|
|
140
|
+
type: 'wp-users';
|
|
141
|
+
args: WpUsersArgs;
|
|
142
|
+
} | {
|
|
143
|
+
type: 'main-query';
|
|
144
|
+
args: WpQueryArgs;
|
|
145
|
+
} | {
|
|
146
|
+
type: 'json';
|
|
147
|
+
data: unknown[];
|
|
148
|
+
};
|
|
149
|
+
/** A loop definition (extensible). */
|
|
150
|
+
interface EtchLoop {
|
|
151
|
+
/** Stable, human-authored key used to reference the loop. */
|
|
152
|
+
key: string;
|
|
153
|
+
/** Display name shown in the loop manager. */
|
|
154
|
+
name: string;
|
|
155
|
+
/** Whether the loop is global (reusable across pages) or local to a document. */
|
|
156
|
+
global: boolean;
|
|
157
|
+
/** The loop's data source and arguments. */
|
|
158
|
+
config: EtchLoopConfig;
|
|
159
|
+
[key: string]: unknown;
|
|
160
|
+
}
|
|
161
|
+
/** All loops keyed by id. */
|
|
162
|
+
type EtchLoopObj = Record<string, EtchLoop>;
|
|
163
|
+
/** Partial loop binding applied to an `etch/loop` block by `loops.setForBlock()`. */
|
|
164
|
+
interface BlockLoopBinding {
|
|
165
|
+
/** Id of the loop to bind. */
|
|
166
|
+
loopId?: string;
|
|
167
|
+
/** What the block iterates over (e.g. the loop's items). */
|
|
168
|
+
target?: string;
|
|
169
|
+
/** Variable name bound to the current item inside the loop. */
|
|
170
|
+
itemId?: string;
|
|
171
|
+
/** Variable name bound to the current index inside the loop. */
|
|
172
|
+
indexId?: string;
|
|
173
|
+
/**
|
|
174
|
+
* Values for the loop's parameters. Every key must be a `$`-prefixed
|
|
175
|
+
* parameter reference (e.g. `$count`), matching the `$param` expressions
|
|
176
|
+
* used in the loop's query args.
|
|
177
|
+
*/
|
|
178
|
+
loopParams?: Record<LoopParamRef, unknown>;
|
|
179
|
+
}
|
|
180
|
+
/** Loop definitions and binding loops to blocks. */
|
|
181
|
+
interface EtchLoopsApi {
|
|
182
|
+
/** All loops keyed by id. */
|
|
183
|
+
getAll(): EtchLoopObj;
|
|
184
|
+
/** Add a new loop; returns its generated id. */
|
|
185
|
+
add(loop: EtchLoop): string;
|
|
186
|
+
/** Replace an existing loop's definition. */
|
|
187
|
+
update(loopId: string, loop: EtchLoop): void;
|
|
188
|
+
/** Delete a loop by id. */
|
|
189
|
+
delete(loopId: string): void;
|
|
190
|
+
/**
|
|
191
|
+
* Fuzzy-search loops by `name` or `key`, ranked best-first. Each hit is the
|
|
192
|
+
* loop plus its `id` (the value `setForBlock`/`update`/`delete` expect).
|
|
193
|
+
* Returns an empty array for a blank query or when nothing matches.
|
|
194
|
+
*/
|
|
195
|
+
findLoop(query: string): (EtchLoop & {
|
|
196
|
+
id: string;
|
|
197
|
+
})[];
|
|
198
|
+
/** Bind (or update the binding of) a loop on an `etch/loop` block. */
|
|
199
|
+
setForBlock(blockId: string, loop: BlockLoopBinding): void;
|
|
200
|
+
}
|
|
201
|
+
|
|
1
202
|
/**
|
|
2
203
|
* Block JSON shapes (read and write) and the `etch.blocks` API surface.
|
|
3
204
|
*/
|
|
205
|
+
|
|
4
206
|
/** A block type identifier, always namespaced under `etch/` (e.g. `etch/text`). */
|
|
5
207
|
type EtchBlockType = `etch/${string}`;
|
|
6
208
|
/** Editor-facing metadata stored on every block. */
|
|
@@ -144,8 +346,11 @@ interface EtchLoopBlockJson extends EtchBlockCommon {
|
|
|
144
346
|
indexId?: string;
|
|
145
347
|
/** Id of a registered loop definition this block is bound to. */
|
|
146
348
|
loopId?: string;
|
|
147
|
-
/**
|
|
148
|
-
|
|
349
|
+
/**
|
|
350
|
+
* Values for the bound loop's parameters. Every key must be a `$`-prefixed
|
|
351
|
+
* parameter reference (e.g. `$count`).
|
|
352
|
+
*/
|
|
353
|
+
loopParams?: Record<LoopParamRef, unknown>;
|
|
149
354
|
}
|
|
150
355
|
/** A conditional block (`etch/condition`); renders its children when the expression holds. */
|
|
151
356
|
interface EtchConditionBlockJson extends EtchBlockCommon {
|
|
@@ -327,6 +532,9 @@ interface EtchBlocksApi {
|
|
|
327
532
|
* Build a block from JSON and insert it; returns the new block id.
|
|
328
533
|
* `parentId` defaults to the document root (`null` is treated the same as
|
|
329
534
|
* omitting it, matching {@link move}), `index` to the end of the parent.
|
|
535
|
+
*
|
|
536
|
+
* Throws `WRONG_BLOCK_TYPE` when `parentId` names a block that cannot contain
|
|
537
|
+
* the new block (e.g. a text or void element).
|
|
330
538
|
*/
|
|
331
539
|
create(json: EtchBlockJson, parentId?: string | null, index?: number): string;
|
|
332
540
|
/** Remove a block and its entire subtree. */
|
|
@@ -336,6 +544,9 @@ interface EtchBlocksApi {
|
|
|
336
544
|
/**
|
|
337
545
|
* Re-parent a block. `newParentId` of `null` moves it to the document root;
|
|
338
546
|
* `index` defaults to the end of the new parent.
|
|
547
|
+
*
|
|
548
|
+
* Throws `WRONG_BLOCK_TYPE` when `newParentId` cannot contain the block; the
|
|
549
|
+
* block is left in its original position.
|
|
339
550
|
*/
|
|
340
551
|
move(blockId: string, newParentId: string | null, index?: number): void;
|
|
341
552
|
/** Replace a block with a new one built from JSON; returns the new block id. */
|
|
@@ -360,6 +571,9 @@ interface EtchBlocksApi {
|
|
|
360
571
|
* - **No `targetId`** (omitted or `null`) — appended to the document root, or
|
|
361
572
|
* inserted there at `index` when given.
|
|
362
573
|
* - **`targetId` + `index`** — inserted as a child of the target at `index`.
|
|
574
|
+
* Throws `WRONG_BLOCK_TYPE` when the target cannot contain the block: an
|
|
575
|
+
* explicit `index` is a deliberate "place it here as a child" request, so
|
|
576
|
+
* an impossible target is an error rather than a silent miss.
|
|
363
577
|
* - **`targetId`, no `index`** — inserted into the target when it accepts
|
|
364
578
|
* children, otherwise immediately after it (handy for "paste near this
|
|
365
579
|
* block").
|
|
@@ -428,203 +642,6 @@ interface EtchBlocksApi {
|
|
|
428
642
|
saveComponentEditModeAsync(): Promise<void>;
|
|
429
643
|
}
|
|
430
644
|
|
|
431
|
-
/**
|
|
432
|
-
* Loop definitions, WordPress query argument shapes, and the `etch.loops` API
|
|
433
|
-
* surface.
|
|
434
|
-
*/
|
|
435
|
-
/**
|
|
436
|
-
* A loop parameter reference, e.g. `$count`. Resolved to a concrete value
|
|
437
|
-
* before the query runs.
|
|
438
|
-
*/
|
|
439
|
-
type LoopParamRef = `$${string}`;
|
|
440
|
-
/**
|
|
441
|
-
* A numeric query value, or a loop-parameter expression that resolves to one:
|
|
442
|
-
* a bare reference (`$count`) or a reference with a numeric fallback
|
|
443
|
-
* (`$count ?? 10`). Plain numeric strings (e.g. `"10"`) are not accepted —
|
|
444
|
-
* pass the number itself.
|
|
445
|
-
*/
|
|
446
|
-
type NumericParam = number | LoopParamRef | `$${string} ?? ${number}`;
|
|
447
|
-
/**
|
|
448
|
-
* A boolean query value, or a loop-parameter expression that resolves to one:
|
|
449
|
-
* a bare reference (`$sticky`) or a reference with a boolean fallback
|
|
450
|
-
* (`$sticky ?? false`). WordPress also accepts its integer-boolean convention
|
|
451
|
-
* (`0`/`1`) for these args.
|
|
452
|
-
*/
|
|
453
|
-
type BooleanParam = boolean | 0 | 1 | LoopParamRef | `$${string} ?? ${boolean}`;
|
|
454
|
-
/**
|
|
455
|
-
* A `WP_Query` meta-query clause. Extensible — additional keys are allowed.
|
|
456
|
-
* @see https://developer.wordpress.org/reference/classes/wp_query/#custom-field-post-meta-parameters
|
|
457
|
-
*/
|
|
458
|
-
interface MetaQueryItem {
|
|
459
|
-
/** The custom field (meta) key to compare. */
|
|
460
|
-
key: string;
|
|
461
|
-
/** The value(s) to compare against. */
|
|
462
|
-
value: string | number | Array<string | number>;
|
|
463
|
-
/** Comparison operator (defaults to `=`). */
|
|
464
|
-
compare?: '=' | '!=' | '>' | '>=' | '<' | '<=' | 'LIKE' | 'NOT LIKE' | 'IN' | 'NOT IN' | 'BETWEEN' | 'NOT BETWEEN' | 'EXISTS' | 'NOT EXISTS';
|
|
465
|
-
/** SQL type the value is cast to before comparison. */
|
|
466
|
-
type?: 'NUMERIC' | 'BINARY' | 'CHAR' | 'DATE' | 'DATETIME' | 'DECIMAL' | 'SIGNED' | 'TIME' | 'UNSIGNED';
|
|
467
|
-
[key: string]: unknown;
|
|
468
|
-
}
|
|
469
|
-
/**
|
|
470
|
-
* A `WP_Query` taxonomy-query clause. Extensible — additional keys are allowed.
|
|
471
|
-
* @see https://developer.wordpress.org/reference/classes/wp_query/#taxonomy-parameters
|
|
472
|
-
*/
|
|
473
|
-
interface TaxQueryItem {
|
|
474
|
-
/** The taxonomy to query (e.g. `category`, `post_tag`). */
|
|
475
|
-
taxonomy: string;
|
|
476
|
-
/** Which term field `terms` refers to. */
|
|
477
|
-
field: 'term_id' | 'slug' | 'name';
|
|
478
|
-
/** The term(s) to match. */
|
|
479
|
-
terms: string | number | Array<string | number>;
|
|
480
|
-
/** How to match the terms (defaults to `IN`). */
|
|
481
|
-
operator?: 'IN' | 'NOT IN' | 'AND';
|
|
482
|
-
/** Whether to include child terms of a hierarchical taxonomy. */
|
|
483
|
-
include_children?: boolean;
|
|
484
|
-
[key: string]: unknown;
|
|
485
|
-
}
|
|
486
|
-
/**
|
|
487
|
-
* WordPress query arguments. Values may be static or a loop parameter
|
|
488
|
-
* expression (`"$param"` or `"$param ?? fallback"`). Extensible — any
|
|
489
|
-
* additional `WP_Query` argument is allowed.
|
|
490
|
-
*/
|
|
491
|
-
interface WpQueryArgs {
|
|
492
|
-
/** Post type(s) to query. */
|
|
493
|
-
post_type?: string | string[];
|
|
494
|
-
/** Number of posts per page (`-1` for all). */
|
|
495
|
-
posts_per_page?: NumericParam;
|
|
496
|
-
/** Number of posts to skip. */
|
|
497
|
-
offset?: NumericParam;
|
|
498
|
-
/** Page of results to return. */
|
|
499
|
-
paged?: NumericParam;
|
|
500
|
-
/** Alias of `paged` used in some contexts. */
|
|
501
|
-
page?: NumericParam;
|
|
502
|
-
/** Field to order results by. */
|
|
503
|
-
orderby?: 'date' | 'title' | 'menu_order' | 'rand' | 'ID' | 'author' | 'name' | 'modified' | 'parent' | 'comment_count' | (string & {});
|
|
504
|
-
/** Sort direction. */
|
|
505
|
-
order?: 'ASC' | 'DESC' | (string & {});
|
|
506
|
-
/** Post status to include. */
|
|
507
|
-
post_status?: 'publish' | 'pending' | 'draft' | 'auto-draft' | 'future' | 'private' | 'inherit' | 'trash' | (string & {});
|
|
508
|
-
/** Whether to ignore sticky posts. */
|
|
509
|
-
ignore_sticky_posts?: BooleanParam;
|
|
510
|
-
/** Author id (number) or username (string). */
|
|
511
|
-
author?: number | string;
|
|
512
|
-
/** Author by `user_nicename`. */
|
|
513
|
-
author_name?: string;
|
|
514
|
-
/** Category id (number) or slug (string). */
|
|
515
|
-
category?: number | string;
|
|
516
|
-
/** Category by slug. */
|
|
517
|
-
category_name?: string;
|
|
518
|
-
/** Tag slug. */
|
|
519
|
-
tag?: string;
|
|
520
|
-
/** Taxonomy query clauses. */
|
|
521
|
-
tax_query?: TaxQueryItem[];
|
|
522
|
-
/** Meta (custom field) query clauses. */
|
|
523
|
-
meta_query?: MetaQueryItem[];
|
|
524
|
-
/** Search keyword. */
|
|
525
|
-
s?: string;
|
|
526
|
-
[key: string]: unknown;
|
|
527
|
-
}
|
|
528
|
-
/** WordPress taxonomy-term query arguments (extensible). */
|
|
529
|
-
interface WpTermsArgs {
|
|
530
|
-
/** Taxonomy to fetch terms from. */
|
|
531
|
-
taxonomy?: string;
|
|
532
|
-
/** Field to order terms by. */
|
|
533
|
-
orderby?: 'name' | 'slug' | 'term_group' | 'term_id' | 'description' | 'count' | (string & {});
|
|
534
|
-
/** Sort direction. */
|
|
535
|
-
order?: 'ASC' | 'DESC' | (string & {});
|
|
536
|
-
[key: string]: unknown;
|
|
537
|
-
}
|
|
538
|
-
/** WordPress user query arguments (extensible). */
|
|
539
|
-
interface WpUsersArgs {
|
|
540
|
-
/** Role(s) users must have. */
|
|
541
|
-
role?: string | string[];
|
|
542
|
-
/** User ids to include. */
|
|
543
|
-
include?: number[] | string;
|
|
544
|
-
/** User ids to exclude. */
|
|
545
|
-
exclude?: number[] | string;
|
|
546
|
-
/** Search keyword. */
|
|
547
|
-
search?: string;
|
|
548
|
-
/** Columns the `search` keyword is matched against. */
|
|
549
|
-
search_columns?: string[] | string;
|
|
550
|
-
/** Field to order users by. */
|
|
551
|
-
orderby?: 'ID' | 'display_name' | 'name' | 'user_login' | 'user_email' | 'user_registered' | 'post_count' | 'meta_value' | 'meta_value_num' | (string & {});
|
|
552
|
-
/** Sort direction. */
|
|
553
|
-
order?: 'ASC' | 'DESC' | (string & {});
|
|
554
|
-
/** Number of users to return. */
|
|
555
|
-
number?: NumericParam;
|
|
556
|
-
/** Number of users to skip. */
|
|
557
|
-
offset?: NumericParam;
|
|
558
|
-
/** Page of results to return. */
|
|
559
|
-
paged?: NumericParam;
|
|
560
|
-
[key: string]: unknown;
|
|
561
|
-
}
|
|
562
|
-
/** Type-specific configuration of an {@link EtchLoop}, discriminated by `type`. */
|
|
563
|
-
type EtchLoopConfig = {
|
|
564
|
-
type: 'wp-query';
|
|
565
|
-
args: WpQueryArgs;
|
|
566
|
-
} | {
|
|
567
|
-
type: 'wp-terms';
|
|
568
|
-
args: WpTermsArgs;
|
|
569
|
-
} | {
|
|
570
|
-
type: 'wp-users';
|
|
571
|
-
args: WpUsersArgs;
|
|
572
|
-
} | {
|
|
573
|
-
type: 'main-query';
|
|
574
|
-
args: WpQueryArgs;
|
|
575
|
-
} | {
|
|
576
|
-
type: 'json';
|
|
577
|
-
data: unknown[];
|
|
578
|
-
};
|
|
579
|
-
/** A loop definition (extensible). */
|
|
580
|
-
interface EtchLoop {
|
|
581
|
-
/** Stable, human-authored key used to reference the loop. */
|
|
582
|
-
key: string;
|
|
583
|
-
/** Display name shown in the loop manager. */
|
|
584
|
-
name: string;
|
|
585
|
-
/** Whether the loop is global (reusable across pages) or local to a document. */
|
|
586
|
-
global: boolean;
|
|
587
|
-
/** The loop's data source and arguments. */
|
|
588
|
-
config: EtchLoopConfig;
|
|
589
|
-
[key: string]: unknown;
|
|
590
|
-
}
|
|
591
|
-
/** All loops keyed by id. */
|
|
592
|
-
type EtchLoopObj = Record<string, EtchLoop>;
|
|
593
|
-
/** Partial loop binding applied to an `etch/loop` block by `loops.setForBlock()`. */
|
|
594
|
-
interface BlockLoopBinding {
|
|
595
|
-
/** Id of the loop to bind. */
|
|
596
|
-
loopId?: string;
|
|
597
|
-
/** What the block iterates over (e.g. the loop's items). */
|
|
598
|
-
target?: string;
|
|
599
|
-
/** Variable name bound to the current item inside the loop. */
|
|
600
|
-
itemId?: string;
|
|
601
|
-
/** Variable name bound to the current index inside the loop. */
|
|
602
|
-
indexId?: string;
|
|
603
|
-
/** Values for the loop's parameters (used by `$param` expressions). */
|
|
604
|
-
loopParams?: Record<string, unknown>;
|
|
605
|
-
}
|
|
606
|
-
/** Loop definitions and binding loops to blocks. */
|
|
607
|
-
interface EtchLoopsApi {
|
|
608
|
-
/** All loops keyed by id. */
|
|
609
|
-
getAll(): EtchLoopObj;
|
|
610
|
-
/** Add a new loop; returns its generated id. */
|
|
611
|
-
add(loop: EtchLoop): string;
|
|
612
|
-
/** Replace an existing loop's definition. */
|
|
613
|
-
update(loopId: string, loop: EtchLoop): void;
|
|
614
|
-
/** Delete a loop by id. */
|
|
615
|
-
delete(loopId: string): void;
|
|
616
|
-
/**
|
|
617
|
-
* Fuzzy-search loops by `name` or `key`, ranked best-first. Each hit is the
|
|
618
|
-
* loop plus its `id` (the value `setForBlock`/`update`/`delete` expect).
|
|
619
|
-
* Returns an empty array for a blank query or when nothing matches.
|
|
620
|
-
*/
|
|
621
|
-
findLoop(query: string): (EtchLoop & {
|
|
622
|
-
id: string;
|
|
623
|
-
})[];
|
|
624
|
-
/** Bind (or update the binding of) a loop on an `etch/loop` block. */
|
|
625
|
-
setForBlock(blockId: string, loop: BlockLoopBinding): void;
|
|
626
|
-
}
|
|
627
|
-
|
|
628
645
|
/**
|
|
629
646
|
* Global style (CSS rule) shapes and the `etch.styles` API surface.
|
|
630
647
|
*/
|
|
@@ -1029,8 +1046,9 @@ interface EtchComponentsApi {
|
|
|
1029
1046
|
* - `content-hub` — the pages/posts browser
|
|
1030
1047
|
* - `style-manager` — the global style manager
|
|
1031
1048
|
* - `loop-manager` — the loop manager
|
|
1049
|
+
* - `asset-manager` — the asset (media) library
|
|
1032
1050
|
*/
|
|
1033
|
-
type NavigationPlace = 'builder' | 'templates' | 'style-manager' | 'content-hub' | 'loop-manager';
|
|
1051
|
+
type NavigationPlace = 'builder' | 'templates' | 'style-manager' | 'content-hub' | 'loop-manager' | 'asset-manager';
|
|
1034
1052
|
/** Lightweight post entry returned by `navigation.listPostsAsync()`. */
|
|
1035
1053
|
interface PostSummary {
|
|
1036
1054
|
/** Post id. */
|
package/dist/index.d.ts
CHANGED
|
@@ -1,6 +1,208 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Loop definitions, WordPress query argument shapes, and the `etch.loops` API
|
|
3
|
+
* surface.
|
|
4
|
+
*/
|
|
5
|
+
/**
|
|
6
|
+
* A loop parameter reference, e.g. `$count`. Resolved to a concrete value
|
|
7
|
+
* before the query runs.
|
|
8
|
+
*/
|
|
9
|
+
type LoopParamRef = `$${string}`;
|
|
10
|
+
/**
|
|
11
|
+
* A numeric query value, or a loop-parameter expression that resolves to one:
|
|
12
|
+
* a bare reference (`$count`) or a reference with a numeric fallback
|
|
13
|
+
* (`$count ?? 10`). Plain numeric strings (e.g. `"10"`) are not accepted —
|
|
14
|
+
* pass the number itself.
|
|
15
|
+
*/
|
|
16
|
+
type NumericParam = number | LoopParamRef | `$${string} ?? ${number}`;
|
|
17
|
+
/**
|
|
18
|
+
* A boolean query value, or a loop-parameter expression that resolves to one:
|
|
19
|
+
* a bare reference (`$sticky`) or a reference with a boolean fallback
|
|
20
|
+
* (`$sticky ?? false`). WordPress also accepts its integer-boolean convention
|
|
21
|
+
* (`0`/`1`) for these args.
|
|
22
|
+
*/
|
|
23
|
+
type BooleanParam = boolean | 0 | 1 | LoopParamRef | `$${string} ?? ${boolean}`;
|
|
24
|
+
/**
|
|
25
|
+
* A `WP_Query` meta-query clause. Extensible — additional keys are allowed.
|
|
26
|
+
* @see https://developer.wordpress.org/reference/classes/wp_query/#custom-field-post-meta-parameters
|
|
27
|
+
*/
|
|
28
|
+
interface MetaQueryItem {
|
|
29
|
+
/** The custom field (meta) key to compare. */
|
|
30
|
+
key: string;
|
|
31
|
+
/** The value(s) to compare against. */
|
|
32
|
+
value: string | number | Array<string | number>;
|
|
33
|
+
/** Comparison operator (defaults to `=`). */
|
|
34
|
+
compare?: '=' | '!=' | '>' | '>=' | '<' | '<=' | 'LIKE' | 'NOT LIKE' | 'IN' | 'NOT IN' | 'BETWEEN' | 'NOT BETWEEN' | 'EXISTS' | 'NOT EXISTS';
|
|
35
|
+
/** SQL type the value is cast to before comparison. */
|
|
36
|
+
type?: 'NUMERIC' | 'BINARY' | 'CHAR' | 'DATE' | 'DATETIME' | 'DECIMAL' | 'SIGNED' | 'TIME' | 'UNSIGNED';
|
|
37
|
+
[key: string]: unknown;
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* A `WP_Query` taxonomy-query clause. Extensible — additional keys are allowed.
|
|
41
|
+
* @see https://developer.wordpress.org/reference/classes/wp_query/#taxonomy-parameters
|
|
42
|
+
*/
|
|
43
|
+
interface TaxQueryItem {
|
|
44
|
+
/** The taxonomy to query (e.g. `category`, `post_tag`). */
|
|
45
|
+
taxonomy: string;
|
|
46
|
+
/** Which term field `terms` refers to. */
|
|
47
|
+
field: 'term_id' | 'slug' | 'name';
|
|
48
|
+
/** The term(s) to match. */
|
|
49
|
+
terms: string | number | Array<string | number>;
|
|
50
|
+
/** How to match the terms (defaults to `IN`). */
|
|
51
|
+
operator?: 'IN' | 'NOT IN' | 'AND';
|
|
52
|
+
/** Whether to include child terms of a hierarchical taxonomy. */
|
|
53
|
+
include_children?: boolean;
|
|
54
|
+
[key: string]: unknown;
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* WordPress query arguments. Values may be static or a loop parameter
|
|
58
|
+
* expression (`"$param"` or `"$param ?? fallback"`). Extensible — any
|
|
59
|
+
* additional `WP_Query` argument is allowed.
|
|
60
|
+
*/
|
|
61
|
+
interface WpQueryArgs {
|
|
62
|
+
/** Post type(s) to query. */
|
|
63
|
+
post_type?: string | string[];
|
|
64
|
+
/** Number of posts per page (`-1` for all). */
|
|
65
|
+
posts_per_page?: NumericParam;
|
|
66
|
+
/** Number of posts to skip. */
|
|
67
|
+
offset?: NumericParam;
|
|
68
|
+
/** Page of results to return. */
|
|
69
|
+
paged?: NumericParam;
|
|
70
|
+
/** Alias of `paged` used in some contexts. */
|
|
71
|
+
page?: NumericParam;
|
|
72
|
+
/** Field to order results by. */
|
|
73
|
+
orderby?: 'date' | 'title' | 'menu_order' | 'rand' | 'ID' | 'author' | 'name' | 'modified' | 'parent' | 'comment_count' | (string & {});
|
|
74
|
+
/** Sort direction. */
|
|
75
|
+
order?: 'ASC' | 'DESC' | (string & {});
|
|
76
|
+
/** Post status to include. */
|
|
77
|
+
post_status?: 'publish' | 'pending' | 'draft' | 'auto-draft' | 'future' | 'private' | 'inherit' | 'trash' | (string & {});
|
|
78
|
+
/** Whether to ignore sticky posts. */
|
|
79
|
+
ignore_sticky_posts?: BooleanParam;
|
|
80
|
+
/** Author id (number) or username (string). */
|
|
81
|
+
author?: number | string;
|
|
82
|
+
/** Author by `user_nicename`. */
|
|
83
|
+
author_name?: string;
|
|
84
|
+
/** Category id (number) or slug (string). */
|
|
85
|
+
category?: number | string;
|
|
86
|
+
/** Category by slug. */
|
|
87
|
+
category_name?: string;
|
|
88
|
+
/** Tag slug. */
|
|
89
|
+
tag?: string;
|
|
90
|
+
/** Taxonomy query clauses. */
|
|
91
|
+
tax_query?: TaxQueryItem[];
|
|
92
|
+
/** Meta (custom field) query clauses. */
|
|
93
|
+
meta_query?: MetaQueryItem[];
|
|
94
|
+
/** Search keyword. */
|
|
95
|
+
s?: string;
|
|
96
|
+
[key: string]: unknown;
|
|
97
|
+
}
|
|
98
|
+
/** WordPress taxonomy-term query arguments (extensible). */
|
|
99
|
+
interface WpTermsArgs {
|
|
100
|
+
/** Taxonomy to fetch terms from. */
|
|
101
|
+
taxonomy?: string;
|
|
102
|
+
/** Field to order terms by. */
|
|
103
|
+
orderby?: 'name' | 'slug' | 'term_group' | 'term_id' | 'description' | 'count' | (string & {});
|
|
104
|
+
/** Sort direction. */
|
|
105
|
+
order?: 'ASC' | 'DESC' | (string & {});
|
|
106
|
+
[key: string]: unknown;
|
|
107
|
+
}
|
|
108
|
+
/** WordPress user query arguments (extensible). */
|
|
109
|
+
interface WpUsersArgs {
|
|
110
|
+
/** Role(s) users must have. */
|
|
111
|
+
role?: string | string[];
|
|
112
|
+
/** User ids to include. */
|
|
113
|
+
include?: number[] | string;
|
|
114
|
+
/** User ids to exclude. */
|
|
115
|
+
exclude?: number[] | string;
|
|
116
|
+
/** Search keyword. */
|
|
117
|
+
search?: string;
|
|
118
|
+
/** Columns the `search` keyword is matched against. */
|
|
119
|
+
search_columns?: string[] | string;
|
|
120
|
+
/** Field to order users by. */
|
|
121
|
+
orderby?: 'ID' | 'display_name' | 'name' | 'user_login' | 'user_email' | 'user_registered' | 'post_count' | 'meta_value' | 'meta_value_num' | (string & {});
|
|
122
|
+
/** Sort direction. */
|
|
123
|
+
order?: 'ASC' | 'DESC' | (string & {});
|
|
124
|
+
/** Number of users to return. */
|
|
125
|
+
number?: NumericParam;
|
|
126
|
+
/** Number of users to skip. */
|
|
127
|
+
offset?: NumericParam;
|
|
128
|
+
/** Page of results to return. */
|
|
129
|
+
paged?: NumericParam;
|
|
130
|
+
[key: string]: unknown;
|
|
131
|
+
}
|
|
132
|
+
/** Type-specific configuration of an {@link EtchLoop}, discriminated by `type`. */
|
|
133
|
+
type EtchLoopConfig = {
|
|
134
|
+
type: 'wp-query';
|
|
135
|
+
args: WpQueryArgs;
|
|
136
|
+
} | {
|
|
137
|
+
type: 'wp-terms';
|
|
138
|
+
args: WpTermsArgs;
|
|
139
|
+
} | {
|
|
140
|
+
type: 'wp-users';
|
|
141
|
+
args: WpUsersArgs;
|
|
142
|
+
} | {
|
|
143
|
+
type: 'main-query';
|
|
144
|
+
args: WpQueryArgs;
|
|
145
|
+
} | {
|
|
146
|
+
type: 'json';
|
|
147
|
+
data: unknown[];
|
|
148
|
+
};
|
|
149
|
+
/** A loop definition (extensible). */
|
|
150
|
+
interface EtchLoop {
|
|
151
|
+
/** Stable, human-authored key used to reference the loop. */
|
|
152
|
+
key: string;
|
|
153
|
+
/** Display name shown in the loop manager. */
|
|
154
|
+
name: string;
|
|
155
|
+
/** Whether the loop is global (reusable across pages) or local to a document. */
|
|
156
|
+
global: boolean;
|
|
157
|
+
/** The loop's data source and arguments. */
|
|
158
|
+
config: EtchLoopConfig;
|
|
159
|
+
[key: string]: unknown;
|
|
160
|
+
}
|
|
161
|
+
/** All loops keyed by id. */
|
|
162
|
+
type EtchLoopObj = Record<string, EtchLoop>;
|
|
163
|
+
/** Partial loop binding applied to an `etch/loop` block by `loops.setForBlock()`. */
|
|
164
|
+
interface BlockLoopBinding {
|
|
165
|
+
/** Id of the loop to bind. */
|
|
166
|
+
loopId?: string;
|
|
167
|
+
/** What the block iterates over (e.g. the loop's items). */
|
|
168
|
+
target?: string;
|
|
169
|
+
/** Variable name bound to the current item inside the loop. */
|
|
170
|
+
itemId?: string;
|
|
171
|
+
/** Variable name bound to the current index inside the loop. */
|
|
172
|
+
indexId?: string;
|
|
173
|
+
/**
|
|
174
|
+
* Values for the loop's parameters. Every key must be a `$`-prefixed
|
|
175
|
+
* parameter reference (e.g. `$count`), matching the `$param` expressions
|
|
176
|
+
* used in the loop's query args.
|
|
177
|
+
*/
|
|
178
|
+
loopParams?: Record<LoopParamRef, unknown>;
|
|
179
|
+
}
|
|
180
|
+
/** Loop definitions and binding loops to blocks. */
|
|
181
|
+
interface EtchLoopsApi {
|
|
182
|
+
/** All loops keyed by id. */
|
|
183
|
+
getAll(): EtchLoopObj;
|
|
184
|
+
/** Add a new loop; returns its generated id. */
|
|
185
|
+
add(loop: EtchLoop): string;
|
|
186
|
+
/** Replace an existing loop's definition. */
|
|
187
|
+
update(loopId: string, loop: EtchLoop): void;
|
|
188
|
+
/** Delete a loop by id. */
|
|
189
|
+
delete(loopId: string): void;
|
|
190
|
+
/**
|
|
191
|
+
* Fuzzy-search loops by `name` or `key`, ranked best-first. Each hit is the
|
|
192
|
+
* loop plus its `id` (the value `setForBlock`/`update`/`delete` expect).
|
|
193
|
+
* Returns an empty array for a blank query or when nothing matches.
|
|
194
|
+
*/
|
|
195
|
+
findLoop(query: string): (EtchLoop & {
|
|
196
|
+
id: string;
|
|
197
|
+
})[];
|
|
198
|
+
/** Bind (or update the binding of) a loop on an `etch/loop` block. */
|
|
199
|
+
setForBlock(blockId: string, loop: BlockLoopBinding): void;
|
|
200
|
+
}
|
|
201
|
+
|
|
1
202
|
/**
|
|
2
203
|
* Block JSON shapes (read and write) and the `etch.blocks` API surface.
|
|
3
204
|
*/
|
|
205
|
+
|
|
4
206
|
/** A block type identifier, always namespaced under `etch/` (e.g. `etch/text`). */
|
|
5
207
|
type EtchBlockType = `etch/${string}`;
|
|
6
208
|
/** Editor-facing metadata stored on every block. */
|
|
@@ -144,8 +346,11 @@ interface EtchLoopBlockJson extends EtchBlockCommon {
|
|
|
144
346
|
indexId?: string;
|
|
145
347
|
/** Id of a registered loop definition this block is bound to. */
|
|
146
348
|
loopId?: string;
|
|
147
|
-
/**
|
|
148
|
-
|
|
349
|
+
/**
|
|
350
|
+
* Values for the bound loop's parameters. Every key must be a `$`-prefixed
|
|
351
|
+
* parameter reference (e.g. `$count`).
|
|
352
|
+
*/
|
|
353
|
+
loopParams?: Record<LoopParamRef, unknown>;
|
|
149
354
|
}
|
|
150
355
|
/** A conditional block (`etch/condition`); renders its children when the expression holds. */
|
|
151
356
|
interface EtchConditionBlockJson extends EtchBlockCommon {
|
|
@@ -327,6 +532,9 @@ interface EtchBlocksApi {
|
|
|
327
532
|
* Build a block from JSON and insert it; returns the new block id.
|
|
328
533
|
* `parentId` defaults to the document root (`null` is treated the same as
|
|
329
534
|
* omitting it, matching {@link move}), `index` to the end of the parent.
|
|
535
|
+
*
|
|
536
|
+
* Throws `WRONG_BLOCK_TYPE` when `parentId` names a block that cannot contain
|
|
537
|
+
* the new block (e.g. a text or void element).
|
|
330
538
|
*/
|
|
331
539
|
create(json: EtchBlockJson, parentId?: string | null, index?: number): string;
|
|
332
540
|
/** Remove a block and its entire subtree. */
|
|
@@ -336,6 +544,9 @@ interface EtchBlocksApi {
|
|
|
336
544
|
/**
|
|
337
545
|
* Re-parent a block. `newParentId` of `null` moves it to the document root;
|
|
338
546
|
* `index` defaults to the end of the new parent.
|
|
547
|
+
*
|
|
548
|
+
* Throws `WRONG_BLOCK_TYPE` when `newParentId` cannot contain the block; the
|
|
549
|
+
* block is left in its original position.
|
|
339
550
|
*/
|
|
340
551
|
move(blockId: string, newParentId: string | null, index?: number): void;
|
|
341
552
|
/** Replace a block with a new one built from JSON; returns the new block id. */
|
|
@@ -360,6 +571,9 @@ interface EtchBlocksApi {
|
|
|
360
571
|
* - **No `targetId`** (omitted or `null`) — appended to the document root, or
|
|
361
572
|
* inserted there at `index` when given.
|
|
362
573
|
* - **`targetId` + `index`** — inserted as a child of the target at `index`.
|
|
574
|
+
* Throws `WRONG_BLOCK_TYPE` when the target cannot contain the block: an
|
|
575
|
+
* explicit `index` is a deliberate "place it here as a child" request, so
|
|
576
|
+
* an impossible target is an error rather than a silent miss.
|
|
363
577
|
* - **`targetId`, no `index`** — inserted into the target when it accepts
|
|
364
578
|
* children, otherwise immediately after it (handy for "paste near this
|
|
365
579
|
* block").
|
|
@@ -428,203 +642,6 @@ interface EtchBlocksApi {
|
|
|
428
642
|
saveComponentEditModeAsync(): Promise<void>;
|
|
429
643
|
}
|
|
430
644
|
|
|
431
|
-
/**
|
|
432
|
-
* Loop definitions, WordPress query argument shapes, and the `etch.loops` API
|
|
433
|
-
* surface.
|
|
434
|
-
*/
|
|
435
|
-
/**
|
|
436
|
-
* A loop parameter reference, e.g. `$count`. Resolved to a concrete value
|
|
437
|
-
* before the query runs.
|
|
438
|
-
*/
|
|
439
|
-
type LoopParamRef = `$${string}`;
|
|
440
|
-
/**
|
|
441
|
-
* A numeric query value, or a loop-parameter expression that resolves to one:
|
|
442
|
-
* a bare reference (`$count`) or a reference with a numeric fallback
|
|
443
|
-
* (`$count ?? 10`). Plain numeric strings (e.g. `"10"`) are not accepted —
|
|
444
|
-
* pass the number itself.
|
|
445
|
-
*/
|
|
446
|
-
type NumericParam = number | LoopParamRef | `$${string} ?? ${number}`;
|
|
447
|
-
/**
|
|
448
|
-
* A boolean query value, or a loop-parameter expression that resolves to one:
|
|
449
|
-
* a bare reference (`$sticky`) or a reference with a boolean fallback
|
|
450
|
-
* (`$sticky ?? false`). WordPress also accepts its integer-boolean convention
|
|
451
|
-
* (`0`/`1`) for these args.
|
|
452
|
-
*/
|
|
453
|
-
type BooleanParam = boolean | 0 | 1 | LoopParamRef | `$${string} ?? ${boolean}`;
|
|
454
|
-
/**
|
|
455
|
-
* A `WP_Query` meta-query clause. Extensible — additional keys are allowed.
|
|
456
|
-
* @see https://developer.wordpress.org/reference/classes/wp_query/#custom-field-post-meta-parameters
|
|
457
|
-
*/
|
|
458
|
-
interface MetaQueryItem {
|
|
459
|
-
/** The custom field (meta) key to compare. */
|
|
460
|
-
key: string;
|
|
461
|
-
/** The value(s) to compare against. */
|
|
462
|
-
value: string | number | Array<string | number>;
|
|
463
|
-
/** Comparison operator (defaults to `=`). */
|
|
464
|
-
compare?: '=' | '!=' | '>' | '>=' | '<' | '<=' | 'LIKE' | 'NOT LIKE' | 'IN' | 'NOT IN' | 'BETWEEN' | 'NOT BETWEEN' | 'EXISTS' | 'NOT EXISTS';
|
|
465
|
-
/** SQL type the value is cast to before comparison. */
|
|
466
|
-
type?: 'NUMERIC' | 'BINARY' | 'CHAR' | 'DATE' | 'DATETIME' | 'DECIMAL' | 'SIGNED' | 'TIME' | 'UNSIGNED';
|
|
467
|
-
[key: string]: unknown;
|
|
468
|
-
}
|
|
469
|
-
/**
|
|
470
|
-
* A `WP_Query` taxonomy-query clause. Extensible — additional keys are allowed.
|
|
471
|
-
* @see https://developer.wordpress.org/reference/classes/wp_query/#taxonomy-parameters
|
|
472
|
-
*/
|
|
473
|
-
interface TaxQueryItem {
|
|
474
|
-
/** The taxonomy to query (e.g. `category`, `post_tag`). */
|
|
475
|
-
taxonomy: string;
|
|
476
|
-
/** Which term field `terms` refers to. */
|
|
477
|
-
field: 'term_id' | 'slug' | 'name';
|
|
478
|
-
/** The term(s) to match. */
|
|
479
|
-
terms: string | number | Array<string | number>;
|
|
480
|
-
/** How to match the terms (defaults to `IN`). */
|
|
481
|
-
operator?: 'IN' | 'NOT IN' | 'AND';
|
|
482
|
-
/** Whether to include child terms of a hierarchical taxonomy. */
|
|
483
|
-
include_children?: boolean;
|
|
484
|
-
[key: string]: unknown;
|
|
485
|
-
}
|
|
486
|
-
/**
|
|
487
|
-
* WordPress query arguments. Values may be static or a loop parameter
|
|
488
|
-
* expression (`"$param"` or `"$param ?? fallback"`). Extensible — any
|
|
489
|
-
* additional `WP_Query` argument is allowed.
|
|
490
|
-
*/
|
|
491
|
-
interface WpQueryArgs {
|
|
492
|
-
/** Post type(s) to query. */
|
|
493
|
-
post_type?: string | string[];
|
|
494
|
-
/** Number of posts per page (`-1` for all). */
|
|
495
|
-
posts_per_page?: NumericParam;
|
|
496
|
-
/** Number of posts to skip. */
|
|
497
|
-
offset?: NumericParam;
|
|
498
|
-
/** Page of results to return. */
|
|
499
|
-
paged?: NumericParam;
|
|
500
|
-
/** Alias of `paged` used in some contexts. */
|
|
501
|
-
page?: NumericParam;
|
|
502
|
-
/** Field to order results by. */
|
|
503
|
-
orderby?: 'date' | 'title' | 'menu_order' | 'rand' | 'ID' | 'author' | 'name' | 'modified' | 'parent' | 'comment_count' | (string & {});
|
|
504
|
-
/** Sort direction. */
|
|
505
|
-
order?: 'ASC' | 'DESC' | (string & {});
|
|
506
|
-
/** Post status to include. */
|
|
507
|
-
post_status?: 'publish' | 'pending' | 'draft' | 'auto-draft' | 'future' | 'private' | 'inherit' | 'trash' | (string & {});
|
|
508
|
-
/** Whether to ignore sticky posts. */
|
|
509
|
-
ignore_sticky_posts?: BooleanParam;
|
|
510
|
-
/** Author id (number) or username (string). */
|
|
511
|
-
author?: number | string;
|
|
512
|
-
/** Author by `user_nicename`. */
|
|
513
|
-
author_name?: string;
|
|
514
|
-
/** Category id (number) or slug (string). */
|
|
515
|
-
category?: number | string;
|
|
516
|
-
/** Category by slug. */
|
|
517
|
-
category_name?: string;
|
|
518
|
-
/** Tag slug. */
|
|
519
|
-
tag?: string;
|
|
520
|
-
/** Taxonomy query clauses. */
|
|
521
|
-
tax_query?: TaxQueryItem[];
|
|
522
|
-
/** Meta (custom field) query clauses. */
|
|
523
|
-
meta_query?: MetaQueryItem[];
|
|
524
|
-
/** Search keyword. */
|
|
525
|
-
s?: string;
|
|
526
|
-
[key: string]: unknown;
|
|
527
|
-
}
|
|
528
|
-
/** WordPress taxonomy-term query arguments (extensible). */
|
|
529
|
-
interface WpTermsArgs {
|
|
530
|
-
/** Taxonomy to fetch terms from. */
|
|
531
|
-
taxonomy?: string;
|
|
532
|
-
/** Field to order terms by. */
|
|
533
|
-
orderby?: 'name' | 'slug' | 'term_group' | 'term_id' | 'description' | 'count' | (string & {});
|
|
534
|
-
/** Sort direction. */
|
|
535
|
-
order?: 'ASC' | 'DESC' | (string & {});
|
|
536
|
-
[key: string]: unknown;
|
|
537
|
-
}
|
|
538
|
-
/** WordPress user query arguments (extensible). */
|
|
539
|
-
interface WpUsersArgs {
|
|
540
|
-
/** Role(s) users must have. */
|
|
541
|
-
role?: string | string[];
|
|
542
|
-
/** User ids to include. */
|
|
543
|
-
include?: number[] | string;
|
|
544
|
-
/** User ids to exclude. */
|
|
545
|
-
exclude?: number[] | string;
|
|
546
|
-
/** Search keyword. */
|
|
547
|
-
search?: string;
|
|
548
|
-
/** Columns the `search` keyword is matched against. */
|
|
549
|
-
search_columns?: string[] | string;
|
|
550
|
-
/** Field to order users by. */
|
|
551
|
-
orderby?: 'ID' | 'display_name' | 'name' | 'user_login' | 'user_email' | 'user_registered' | 'post_count' | 'meta_value' | 'meta_value_num' | (string & {});
|
|
552
|
-
/** Sort direction. */
|
|
553
|
-
order?: 'ASC' | 'DESC' | (string & {});
|
|
554
|
-
/** Number of users to return. */
|
|
555
|
-
number?: NumericParam;
|
|
556
|
-
/** Number of users to skip. */
|
|
557
|
-
offset?: NumericParam;
|
|
558
|
-
/** Page of results to return. */
|
|
559
|
-
paged?: NumericParam;
|
|
560
|
-
[key: string]: unknown;
|
|
561
|
-
}
|
|
562
|
-
/** Type-specific configuration of an {@link EtchLoop}, discriminated by `type`. */
|
|
563
|
-
type EtchLoopConfig = {
|
|
564
|
-
type: 'wp-query';
|
|
565
|
-
args: WpQueryArgs;
|
|
566
|
-
} | {
|
|
567
|
-
type: 'wp-terms';
|
|
568
|
-
args: WpTermsArgs;
|
|
569
|
-
} | {
|
|
570
|
-
type: 'wp-users';
|
|
571
|
-
args: WpUsersArgs;
|
|
572
|
-
} | {
|
|
573
|
-
type: 'main-query';
|
|
574
|
-
args: WpQueryArgs;
|
|
575
|
-
} | {
|
|
576
|
-
type: 'json';
|
|
577
|
-
data: unknown[];
|
|
578
|
-
};
|
|
579
|
-
/** A loop definition (extensible). */
|
|
580
|
-
interface EtchLoop {
|
|
581
|
-
/** Stable, human-authored key used to reference the loop. */
|
|
582
|
-
key: string;
|
|
583
|
-
/** Display name shown in the loop manager. */
|
|
584
|
-
name: string;
|
|
585
|
-
/** Whether the loop is global (reusable across pages) or local to a document. */
|
|
586
|
-
global: boolean;
|
|
587
|
-
/** The loop's data source and arguments. */
|
|
588
|
-
config: EtchLoopConfig;
|
|
589
|
-
[key: string]: unknown;
|
|
590
|
-
}
|
|
591
|
-
/** All loops keyed by id. */
|
|
592
|
-
type EtchLoopObj = Record<string, EtchLoop>;
|
|
593
|
-
/** Partial loop binding applied to an `etch/loop` block by `loops.setForBlock()`. */
|
|
594
|
-
interface BlockLoopBinding {
|
|
595
|
-
/** Id of the loop to bind. */
|
|
596
|
-
loopId?: string;
|
|
597
|
-
/** What the block iterates over (e.g. the loop's items). */
|
|
598
|
-
target?: string;
|
|
599
|
-
/** Variable name bound to the current item inside the loop. */
|
|
600
|
-
itemId?: string;
|
|
601
|
-
/** Variable name bound to the current index inside the loop. */
|
|
602
|
-
indexId?: string;
|
|
603
|
-
/** Values for the loop's parameters (used by `$param` expressions). */
|
|
604
|
-
loopParams?: Record<string, unknown>;
|
|
605
|
-
}
|
|
606
|
-
/** Loop definitions and binding loops to blocks. */
|
|
607
|
-
interface EtchLoopsApi {
|
|
608
|
-
/** All loops keyed by id. */
|
|
609
|
-
getAll(): EtchLoopObj;
|
|
610
|
-
/** Add a new loop; returns its generated id. */
|
|
611
|
-
add(loop: EtchLoop): string;
|
|
612
|
-
/** Replace an existing loop's definition. */
|
|
613
|
-
update(loopId: string, loop: EtchLoop): void;
|
|
614
|
-
/** Delete a loop by id. */
|
|
615
|
-
delete(loopId: string): void;
|
|
616
|
-
/**
|
|
617
|
-
* Fuzzy-search loops by `name` or `key`, ranked best-first. Each hit is the
|
|
618
|
-
* loop plus its `id` (the value `setForBlock`/`update`/`delete` expect).
|
|
619
|
-
* Returns an empty array for a blank query or when nothing matches.
|
|
620
|
-
*/
|
|
621
|
-
findLoop(query: string): (EtchLoop & {
|
|
622
|
-
id: string;
|
|
623
|
-
})[];
|
|
624
|
-
/** Bind (or update the binding of) a loop on an `etch/loop` block. */
|
|
625
|
-
setForBlock(blockId: string, loop: BlockLoopBinding): void;
|
|
626
|
-
}
|
|
627
|
-
|
|
628
645
|
/**
|
|
629
646
|
* Global style (CSS rule) shapes and the `etch.styles` API surface.
|
|
630
647
|
*/
|
|
@@ -1029,8 +1046,9 @@ interface EtchComponentsApi {
|
|
|
1029
1046
|
* - `content-hub` — the pages/posts browser
|
|
1030
1047
|
* - `style-manager` — the global style manager
|
|
1031
1048
|
* - `loop-manager` — the loop manager
|
|
1049
|
+
* - `asset-manager` — the asset (media) library
|
|
1032
1050
|
*/
|
|
1033
|
-
type NavigationPlace = 'builder' | 'templates' | 'style-manager' | 'content-hub' | 'loop-manager';
|
|
1051
|
+
type NavigationPlace = 'builder' | 'templates' | 'style-manager' | 'content-hub' | 'loop-manager' | 'asset-manager';
|
|
1034
1052
|
/** Lightweight post entry returned by `navigation.listPostsAsync()`. */
|
|
1035
1053
|
interface PostSummary {
|
|
1036
1054
|
/** Post id. */
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@digital-gravy/etch-public-api",
|
|
3
|
-
"version": "0.7.
|
|
3
|
+
"version": "0.7.4",
|
|
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
|
"repository": {
|