@digital-gravy/etch-public-api 0.1.0 → 0.1.1

package/dist/index.d.cts

@@ -163,6 +163,25 @@ interface EtchBlocksApi {
     /** Whether the block currently has the given CSS class. */
     hasClass(blockId: string, className: string): boolean;
 }
+/**
+ * A loop parameter reference, e.g. `$count`. Resolved to a concrete value
+ * before the query runs.
+ */
+type LoopParamRef = `$${string}`;
+/**
+ * A numeric query value, or a loop-parameter expression that resolves to one:
+ * a bare reference (`$count`) or a reference with a numeric fallback
+ * (`$count ?? 10`). Plain numeric strings (e.g. `"10"`) are not accepted —
+ * pass the number itself.
+ */
+type NumericParam = number | LoopParamRef | `$${string} ?? ${number}`;
+/**
+ * A boolean query value, or a loop-parameter expression that resolves to one:
+ * a bare reference (`$sticky`) or a reference with a boolean fallback
+ * (`$sticky ?? false`). WordPress also accepts its integer-boolean convention
+ * (`0`/`1`) for these args.
+ */
+type BooleanParam = boolean | 0 | 1 | LoopParamRef | `$${string} ?? ${boolean}`;
 /**
  * A `WP_Query` meta-query clause. Extensible — additional keys are allowed.
  * @see https://developer.wordpress.org/reference/classes/wp_query/#custom-field-post-meta-parameters
@@ -204,13 +223,13 @@ interface WpQueryArgs {
     /** Post type(s) to query. */
     post_type?: string | string[];
     /** Number of posts per page (`-1` for all). */
-    posts_per_page?: number | string;
+    posts_per_page?: NumericParam;
     /** Number of posts to skip. */
-    offset?: number | string;
+    offset?: NumericParam;
     /** Page of results to return. */
-    paged?: number | string;
+    paged?: NumericParam;
     /** Alias of `paged` used in some contexts. */
-    page?: number | string;
+    page?: NumericParam;
     /** Field to order results by. */
     orderby?: "date" | "title" | "menu_order" | "rand" | "ID" | "author" | "name" | "modified" | "parent" | "comment_count" | (string & {});
     /** Sort direction. */
@@ -218,7 +237,7 @@ interface WpQueryArgs {
     /** Post status to include. */
     post_status?: "publish" | "pending" | "draft" | "auto-draft" | "future" | "private" | "inherit" | "trash" | (string & {});
     /** Whether to ignore sticky posts. */
-    ignore_sticky_posts?: boolean | 0 | 1 | (string & {});
+    ignore_sticky_posts?: BooleanParam;
     /** Author id (number) or username (string). */
     author?: number | string;
     /** Author by `user_nicename`. */
@@ -264,11 +283,11 @@ interface WpUsersArgs {
     /** Sort direction. */
     order?: "ASC" | "DESC" | (string & {});
     /** Number of users to return. */
-    number?: number | string;
+    number?: NumericParam;
     /** Number of users to skip. */
-    offset?: number | string;
+    offset?: NumericParam;
     /** Page of results to return. */
-    paged?: number | string;
+    paged?: NumericParam;
     [key: string]: unknown;
 }
 /** Type-specific configuration of an {@link EtchLoop}, discriminated by `type`. */
@@ -881,4 +900,4 @@ declare function isEtchApiError(value: unknown): value is EtchApiError;
  */
 declare const ETCH_API_VERSION = "0.x";
 
-export { type ArrayComponentProperty, type BlockLoopBinding, type BlockPatch, type BooleanComponentProperty, type 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 };
+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 };

package/dist/index.d.ts

@@ -163,6 +163,25 @@ interface EtchBlocksApi {
     /** Whether the block currently has the given CSS class. */
     hasClass(blockId: string, className: string): boolean;
 }
+/**
+ * A loop parameter reference, e.g. `$count`. Resolved to a concrete value
+ * before the query runs.
+ */
+type LoopParamRef = `$${string}`;
+/**
+ * A numeric query value, or a loop-parameter expression that resolves to one:
+ * a bare reference (`$count`) or a reference with a numeric fallback
+ * (`$count ?? 10`). Plain numeric strings (e.g. `"10"`) are not accepted —
+ * pass the number itself.
+ */
+type NumericParam = number | LoopParamRef | `$${string} ?? ${number}`;
+/**
+ * A boolean query value, or a loop-parameter expression that resolves to one:
+ * a bare reference (`$sticky`) or a reference with a boolean fallback
+ * (`$sticky ?? false`). WordPress also accepts its integer-boolean convention
+ * (`0`/`1`) for these args.
+ */
+type BooleanParam = boolean | 0 | 1 | LoopParamRef | `$${string} ?? ${boolean}`;
 /**
  * A `WP_Query` meta-query clause. Extensible — additional keys are allowed.
  * @see https://developer.wordpress.org/reference/classes/wp_query/#custom-field-post-meta-parameters
@@ -204,13 +223,13 @@ interface WpQueryArgs {
     /** Post type(s) to query. */
     post_type?: string | string[];
     /** Number of posts per page (`-1` for all). */
-    posts_per_page?: number | string;
+    posts_per_page?: NumericParam;
     /** Number of posts to skip. */
-    offset?: number | string;
+    offset?: NumericParam;
     /** Page of results to return. */
-    paged?: number | string;
+    paged?: NumericParam;
     /** Alias of `paged` used in some contexts. */
-    page?: number | string;
+    page?: NumericParam;
     /** Field to order results by. */
     orderby?: "date" | "title" | "menu_order" | "rand" | "ID" | "author" | "name" | "modified" | "parent" | "comment_count" | (string & {});
     /** Sort direction. */
@@ -218,7 +237,7 @@ interface WpQueryArgs {
     /** Post status to include. */
     post_status?: "publish" | "pending" | "draft" | "auto-draft" | "future" | "private" | "inherit" | "trash" | (string & {});
     /** Whether to ignore sticky posts. */
-    ignore_sticky_posts?: boolean | 0 | 1 | (string & {});
+    ignore_sticky_posts?: BooleanParam;
     /** Author id (number) or username (string). */
     author?: number | string;
     /** Author by `user_nicename`. */
@@ -264,11 +283,11 @@ interface WpUsersArgs {
     /** Sort direction. */
     order?: "ASC" | "DESC" | (string & {});
     /** Number of users to return. */
-    number?: number | string;
+    number?: NumericParam;
     /** Number of users to skip. */
-    offset?: number | string;
+    offset?: NumericParam;
     /** Page of results to return. */
-    paged?: number | string;
+    paged?: NumericParam;
     [key: string]: unknown;
 }
 /** Type-specific configuration of an {@link EtchLoop}, discriminated by `type`. */
@@ -881,4 +900,4 @@ declare function isEtchApiError(value: unknown): value is EtchApiError;
  */
 declare const ETCH_API_VERSION = "0.x";
 
-export { type ArrayComponentProperty, type BlockLoopBinding, type BlockPatch, type BooleanComponentProperty, type 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 };
+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 };

package/package.json

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