@digital-gravy/etch-public-api 0.3.0 → 0.3.2

package/dist/index.d.cts

@@ -112,6 +112,16 @@ interface EtchDynamicElementBlockJson extends EtchBlockCommon {
  *
  * The global `styles` applied to the block are **read-only** (see
  * {@link EtchElementBlockJson}).
+ *
+ * **Special attributes** (in addition to standard `<img>` attributes):
+ * - `mediaId` — WordPress attachment post ID. When set, Etch fetches the media
+ *   object and uses its URL as `src`, overriding any explicit `src` attribute.
+ *   Supports dynamic expressions (`{post.featured_image_id}`).
+ * - `useSrcSet` — `"true"` to generate a responsive `srcset` from the media
+ *   (only effective when `mediaId` is set).
+ * - `maximumSize` — maximum WordPress image size slug (e.g. `"large"`,
+ *   `"full"`) used when building `srcset` / resolving the image URL. Defaults
+ *   to `"full"` when omitted.
  */
 interface EtchDynamicImageBlockJson extends EtchBlockCommon {
     type: "etch/dynamic-image";
@@ -123,6 +133,13 @@ interface EtchDynamicImageBlockJson extends EtchBlockCommon {
  *
  * The global `styles` applied to the block are **read-only** (see
  * {@link EtchElementBlockJson}).
+ *
+ * **Special attributes** (in addition to standard SVG attributes):
+ * - `src` — URL of an external `.svg` file. When set, Etch fetches the file and
+ *   inlines its contents at render time. Supports dynamic expressions.
+ * - `stripColors` — `"true"` to strip `fill` and `stroke` colour declarations
+ *   from the fetched SVG so CSS can drive its colours instead. Only effective
+ *   when `src` is set.
  */
 interface EtchSvgBlockJson extends EtchBlockCommon {
     type: "etch/svg";
@@ -636,7 +653,13 @@ interface StringComponentProperty {
      */
     selectOptionsString?: SelectOptionsString;
 }
-/** A numeric property. */
+/**
+ * A numeric property.
+ *
+ * Note: number properties are **not implemented in the builder yet** — they are
+ * reserved in the contract but you can't create or edit one today. Don't rely
+ * on them.
+ */
 interface NumberComponentProperty {
     type: {
         primitive: "number";
@@ -730,8 +753,8 @@ interface ConditionComponentProperty {
  *
  * - `string` — plain text; or `'image'` | `'wpMediaId'` | `'select'` |
  *   `'array'`; or `'condition'` (a gated group with nested `properties`)
- * - `number` — numeric
  * - `boolean` — boolean
+ * - `number` — numeric (reserved; not implemented in the builder yet)
  * - `object` — generic object; or `'group'` (nested `properties`)
  * - `array` — generic array; or `'class'` (CSS classes); or `'repeater'`
  *   (repeating group with nested `properties`)
@@ -758,7 +781,11 @@ interface PublicComponentSummary {
     id: number;
     /** Display name. */
     name: string;
-    /** Stable key used to reference the component in markup. */
+    /**
+     * Stable key used to reference the component in markup (e.g. `<Card />`).
+     * Always **PascalCase**: starts with an uppercase letter, letters and digits
+     * only (no dashes, underscores, or spaces).
+     */
     key: string;
     /** Optional human-readable description. */
     description?: string;
@@ -774,7 +801,11 @@ interface PublicComponentJson extends PublicComponentSummary {
 interface ComponentPatch {
     /** New display name. */
     name?: string;
-    /** New reference key. */
+    /**
+     * New reference key. It is **converted to PascalCase** before it is stored
+     * (e.g. `my card` → `MyCard`), so the key actually saved may differ from the
+     * string passed here.
+     */
     key?: string;
     /** New description. */
     description?: string;

package/dist/index.d.ts

@@ -112,6 +112,16 @@ interface EtchDynamicElementBlockJson extends EtchBlockCommon {
  *
  * The global `styles` applied to the block are **read-only** (see
  * {@link EtchElementBlockJson}).
+ *
+ * **Special attributes** (in addition to standard `<img>` attributes):
+ * - `mediaId` — WordPress attachment post ID. When set, Etch fetches the media
+ *   object and uses its URL as `src`, overriding any explicit `src` attribute.
+ *   Supports dynamic expressions (`{post.featured_image_id}`).
+ * - `useSrcSet` — `"true"` to generate a responsive `srcset` from the media
+ *   (only effective when `mediaId` is set).
+ * - `maximumSize` — maximum WordPress image size slug (e.g. `"large"`,
+ *   `"full"`) used when building `srcset` / resolving the image URL. Defaults
+ *   to `"full"` when omitted.
  */
 interface EtchDynamicImageBlockJson extends EtchBlockCommon {
     type: "etch/dynamic-image";
@@ -123,6 +133,13 @@ interface EtchDynamicImageBlockJson extends EtchBlockCommon {
  *
  * The global `styles` applied to the block are **read-only** (see
  * {@link EtchElementBlockJson}).
+ *
+ * **Special attributes** (in addition to standard SVG attributes):
+ * - `src` — URL of an external `.svg` file. When set, Etch fetches the file and
+ *   inlines its contents at render time. Supports dynamic expressions.
+ * - `stripColors` — `"true"` to strip `fill` and `stroke` colour declarations
+ *   from the fetched SVG so CSS can drive its colours instead. Only effective
+ *   when `src` is set.
  */
 interface EtchSvgBlockJson extends EtchBlockCommon {
     type: "etch/svg";
@@ -636,7 +653,13 @@ interface StringComponentProperty {
      */
     selectOptionsString?: SelectOptionsString;
 }
-/** A numeric property. */
+/**
+ * A numeric property.
+ *
+ * Note: number properties are **not implemented in the builder yet** — they are
+ * reserved in the contract but you can't create or edit one today. Don't rely
+ * on them.
+ */
 interface NumberComponentProperty {
     type: {
         primitive: "number";
@@ -730,8 +753,8 @@ interface ConditionComponentProperty {
  *
  * - `string` — plain text; or `'image'` | `'wpMediaId'` | `'select'` |
  *   `'array'`; or `'condition'` (a gated group with nested `properties`)
- * - `number` — numeric
  * - `boolean` — boolean
+ * - `number` — numeric (reserved; not implemented in the builder yet)
  * - `object` — generic object; or `'group'` (nested `properties`)
  * - `array` — generic array; or `'class'` (CSS classes); or `'repeater'`
  *   (repeating group with nested `properties`)
@@ -758,7 +781,11 @@ interface PublicComponentSummary {
     id: number;
     /** Display name. */
     name: string;
-    /** Stable key used to reference the component in markup. */
+    /**
+     * Stable key used to reference the component in markup (e.g. `<Card />`).
+     * Always **PascalCase**: starts with an uppercase letter, letters and digits
+     * only (no dashes, underscores, or spaces).
+     */
     key: string;
     /** Optional human-readable description. */
     description?: string;
@@ -774,7 +801,11 @@ interface PublicComponentJson extends PublicComponentSummary {
 interface ComponentPatch {
     /** New display name. */
     name?: string;
-    /** New reference key. */
+    /**
+     * New reference key. It is **converted to PascalCase** before it is stored
+     * (e.g. `my card` → `MyCard`), so the key actually saved may differ from the
+     * string passed here.
+     */
     key?: string;
     /** New description. */
     description?: string;

package/package.json

@@ -1,43 +1,46 @@
 {
-	"name": "@digital-gravy/etch-public-api",
-	"version": "0.3.0",
-	"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",
-	"main": "./dist/index.cjs",
-	"module": "./dist/index.js",
-	"types": "./dist/index.d.ts",
-	"exports": {
-		".": {
-			"types": "./dist/index.d.ts",
-			"import": "./dist/index.js",
-			"require": "./dist/index.cjs"
-		}
-	},
-	"files": ["dist", "README.md"],
-	"sideEffects": false,
-	"scripts": {
-		"build": "tsup",
-		"dev": "tsup --watch",
-		"test": "vitest run",
-		"test:watch": "vitest",
-		"typecheck": "tsc --noEmit",
-		"prepublishOnly": "bun run build"
-	},
-	"keywords": [
-		"etch",
-		"etchwp",
-		"wordpress",
-		"builder",
-		"scripting",
-		"api"
-	],
-	"publishConfig": {
-		"access": "public"
-	},
-	"devDependencies": {
-		"tsup": "^8.3.5",
-		"typescript": "^5.7.2",
-		"vitest": "^3.0.5"
-	}
+  "name": "@digital-gravy/etch-public-api",
+  "version": "0.3.2",
+  "description": "MIT-licensed typed client and contract for the Etch builder scripting API (window.etch). Etch itself is a separate proprietary product governed by its own commercial terms.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "etch",
+    "etchwp",
+    "wordpress",
+    "builder",
+    "scripting",
+    "api"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^3.0.5"
+  }
 }